<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

<html xmlns="https://www.w3.org/1999/xhtml">
  <head>
    <meta name="generator" content="HTML Tidy for Linux/x86 (vers 7 December 2008), see www.w3.org" />

    <title>RMagick 0.0.0: class Image (class methods and instance methods a-d)</title>
    <meta http-equiv="Content-Type" content="text/html; charset=us-ascii" />
    <meta name="GENERATOR" content="Quanta Plus" />
    <meta name="Copyright" content="Copyright (C) 2006 by Timothy P. Hunter" />
    <link rel="stylesheet" type="text/css" href="css/doc.css" />
    <script type="text/javascript" src="scripts/doc.js"></script>
    <script type="text/javascript">
      //<![CDATA[
      <!-- Pre-load this image so that the browser knows how big it is. -->
      flower_hat = new Image();
      flower_hat.src = "ex/images/Flower_Hat.jpg";
      function show_noise(type) {
        if (type == null) {
          document.getElementById("add_noise_example").src = "ex/images/Flower_Hat.jpg";
        } else {
          document.getElementById("add_noise_example").src = "ex/add_noise_" + type + ".jpg";
        }
      }
      //]]>
    </script>
    <style type="text/css">
      /*<![CDATA[*/
      .noise_example_wrapper img {
        float: left;
      }
      .noise_example_wrapper p,
      .noise_example_wrapper ul {
        margin-left: 4px;
        float: left;
      }
      /*]]>*/
    </style>
  </head>

  <body>
    <h6 id="header">RMagick 0.0.0 User's Guide and Reference</h6>

    <div class="nav">&laquo;&nbsp;<a href="imageattrs.html">Prev</a> | <a href="index.html">Contents</a> | <a href="image2.html">Next</a>&nbsp;&raquo;</div>

    <h1>
      class Image <span class="superclass">&lt; Object</span> (class methods and instance methods a-d)<br />
      <span class="mixin">mixes in Comparable</span>
    </h1>

    <div id="toc">
      <h2>Table of Contents</h2>

      <h3>class methods</h3>

      <div>
        <div class="toccol">
          <ul>
            <li><a href="#capture">capture</a></li>

            <li><a href="#combine">combine</a></li>

            <li><a href="#constitute">constitute</a></li>
          </ul>
        </div>

        <div class="toccol">
          <ul>
            <li><a href="#from_blob">from_blob</a></li>

            <li><a href="#new">new</a></li>

            <li><a href="#ping">ping</a></li>
          </ul>
        </div>

        <div class="toccol">
          <ul>
            <li><a href="#read">read</a></li>

            <li><a href="#read_inline">read_inline</a></li>
          </ul>
        </div>
      </div>

      <h3>instance methods</h3>

      <div>
        <div class="toccol">
          <ul>
            <li><a href="#aref">[&nbsp;]</a></li>

            <li><a href="#aset">[&nbsp;]=</a></li>

            <li><a href="#spaceship">&lt;=&gt;</a></li>

            <li><a href="#adaptive_blur">adaptive_blur</a></li>

            <li><a href="#adaptive_blur_channel">adaptive_blur_channel</a></li>

            <li><a href="#adaptive_resize">adaptive_resize</a></li>

            <li><a href="#adaptive_sharpen">adaptive_sharpen</a></li>

            <li>
              <a href="#adaptive_sharpen_channel">adaptive_sharpen_channel</a>
            </li>

            <li><a href="#adaptive_threshold">adaptive_threshold</a></li>

            <li><a href="#add_compose_mask">add_compose_mask</a></li>

            <li><a href="#add_noise">add_noise</a></li>

            <li><a href="#add_noise_channel">add_noise_channel</a></li>

            <li><a href="#add_profile">add_profile</a></li>

            <li><a href="#affine_transform">affine_transform</a></li>

            <li><a href="#alpha">alpha</a></li>

            <li><a href="#alpha_q">alpha?</a></li>

            <li><a href="#annotate">annotate</a></li>

            <li><a href="#auto_gamma_channel">auto_gamma_channel</a></li>

            <li><a href="#auto_level_channel">auto_level_channel</a></li>

            <li><a href="#auto_orient">auto_orient</a></li>

            <li><a href="#auto_orient_bang">auto_orient!</a></li>

            <li><a href="#bilevel_channel">bilevel_channel</a></li>

            <li><a href="#black_threshold">black_threshold</a></li>

            <li><a href="#blend">blend</a></li>

            <li><a href="#blue_shift">blue_shift</a></li>

            <li><a href="#blur_channel">blur_channel</a></li>

            <li><a href="#blur_image">blur_image</a></li>
          </ul>
        </div>

        <div class="toccol">
          <ul>
            <li><a href="#border">border</a></li>

            <li><a href="#border_bang">border!</a></li>

            <li><a href="#bounding_box">bounding_box</a></li>

            <li><a href="#change_geometry">change_geometry</a></li>

            <li><a href="#changed_q">changed?</a></li>

            <li><a href="#channel">channel</a></li>

            <li><a href="#channel_depth">channel_depth</a></li>

            <li><a href="#channel_extrema">channel_extrema</a></li>

            <li><a href="#channel_mean">channel_mean</a></li>

            <li><a href="#charcoal">charcoal</a></li>

            <li><a href="#check_destroyed">check_destroyed</a></li>

            <li><a href="#chop">chop</a></li>

            <li><a href="#clone">clone</a></li>

            <li><a href="#clut_channel">clut_channel</a></li>

            <li><a href="#color_fill_to_border">color_fill_to_border</a></li>

            <li><a href="#color_floodfill">color_floodfill</a></li>

            <li><a href="#color_histogram">color_histogram</a></li>

            <li><a href="#colorize">colorize</a></li>

            <li><a href="#colormap">colormap</a></li>

            <li><a href="#color_point">color_point</a></li>

            <li><a href="#color_reset_bang">color_reset!</a></li>

            <li><a href="#compare_channel">compare_channel</a></li>

            <li><a href="#composite">composite</a></li>

            <li><a href="#composite_bang">composite!</a></li>

            <li><a href="#composite_affine">composite_affine</a></li>

            <li><a href="#composite_mathematics">composite_mathematics</a></li>

            <li><a href="#composite_tiled">composite_tiled</a></li>
          </ul>
        </div>

        <div class="toccol">
          <ul>
            <li><a href="#composite_tiled_bang">composite_tiled!</a></li>

            <li><a href="#compress_colormap_bang">compress_colormap!</a></li>

            <li><a href="#contrast">contrast</a></li>

            <li>
              <a href="#contrast_stretch_channel">contrast_stretch_channel</a>
            </li>

            <li><a href="#convolve">convolve</a></li>

            <li><a href="#convolve_channel">convolve_channel</a></li>

            <li><a href="#copy">copy</a></li>

            <li><a href="#crop">crop</a></li>

            <li><a href="#crop_bang">crop!</a></li>

            <li><a href="#crop_resized">crop_resized</a></li>

            <li><a href="#cycle_colormap">cycle_colormap</a></li>

            <li><a href="#decipher">decipher</a></li>

            <li><a href="#delete_compose_mask">delete_compose_mask</a></li>

            <li><a href="#delete_profile">delete_profile</a></li>

            <li><a href="#deskew">deskew</a></li>

            <li><a href="#despeckle">despeckle</a></li>

            <li><a href="#destroy_bang">destroy!</a></li>

            <li><a href="#destroyed_q">destroyed?</a></li>

            <li><a href="#difference">difference</a></li>

            <li><a href="#dispatch">dispatch</a></li>

            <li><a href="#displace">displace</a></li>

            <li><a href="#display">display</a></li>

            <li><a href="#dissolve">dissolve</a></li>

            <li><a href="#distort">distort</a></li>

            <li><a href="#distortion_channel">distortion_channel</a></li>

            <li><a href="#dup">dup</a></li>
          </ul>
        </div>
      </div>
    </div>

    <h2 class="methods">class methods</h2>

    <div class="sig">
      <h3 id="capture">capture</h3>

      <p>
        Image.capture(<span class="arg">silent=</span><code>false</code>, <span class="arg">frame=</span><code>false</code>, <span class="arg">descend=</span
        ><code>false</code>, <span class="arg">screen=</span><code>false</code>, <span class="arg">borders=</span><code>false</code>) [
        <span class="arg">{&nbsp;optional arguments&nbsp;}</span> ] -&gt;
        <em>image</em>
      </p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>
        Reads an image from an X window. Unless you identify a window to capture via the <em>optional arguments</em> block, when <code>capture</code> is invoked
        the cursor will turn into a cross. Click the cursor on the window to be captured.
      </p>

      <p>
        Within the optional arguments block, specify
        <code>options.filename = "root"</code> to capture the entire desktop. To programatically specify the window to be captured, use
        <code>options.filename = window_id</code>, where window_id is the id displayed by xwininfo(1).
      </p>

      <h4>Arguments</h4>

      <dl>
        <dt>silent</dt>

        <dd>
          If <code>true</code>, suppress the beeps that signal the start and finish of the capture process. The bell rings once to signal the start of the
          capture and twice to signal the finish.
        </dd>

        <dt>frame</dt>

        <dd>If <code>true</code>, include the window frame.</dd>

        <dt>descend</dt>

        <dd>
          If <code>true</code>,
          <span class="imquote">obtain image by descending window hierarchy.</span>
        </dd>

        <dt>screen</dt>

        <dd>
          If <code>true</code>, specifies that
          <span class="imquote"
            >the GetImage request used to obtain the image should be done on the root window, rather than directly on the specified window. In this way, you can
            obtain pieces of other windows that overlap the specified window, and more importantly, you can capture menus or other popups that are independent
            windows but appear over the specified window.</span
          >
        </dd>

        <dt>borders</dt>

        <dd>If <code>true</code>, include the border in the image.</dd>

        <dt>optional arguments</dt>

        <dd>
          You can specify any of these Image::Info attributes in the
          <em>optional arguments</em> block: <a href="info.html#colorspace">colorspace</a>, <a href="info.html#depth">depth</a>,
          <a href="info.html#dither">dither</a>, <a href="info.html#interlace">interlace</a>, and <a href="info.html#type">type</a>.
        </dd>
      </dl>

      <h4>Returns</h4>

      <p>A new image.</p>

      <h4>Example</h4>
      <pre>
img = Image.capture { |options|
  options.filename = "root"
}
</pre
      >
    </div>

    <div class="sig">
      <h3 id="combine">combine</h3>

      <p>
        Image.combine(<span class="arg">red_ch</span>=nil, <span class="arg">green_ch</span>=nil, <span class="arg">blue_ch</span>=nil<span class="arg"
          >, opacity_ch</span
        >=nil) -&gt;<em>image</em>
      </p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>Combines the grayscale value of the pixels in each image to form a new image.</p>

      <h4>Arguments</h4>

      <p>
        The red channel of the image specified in the first argument is used as the red channel in the new image. The green channel of the image specified in
        the second argument is used as the green channel in the new image. The blue channel of the image specified in the third argument is used as the blue
        channel in the new image. The opacity channel of the image specified in the fourth argument is used as the opacity channel in the new image.
      </p>

      <p>Any of the arguments may be nil. Trailing nil arguments may be omitted. You must specify at least one image argument.</p>

      <h4>Returns</h4>

      <p>A new image</p>

      <h4>See also</h4>

      <p>
        The same results can be obtained using the
        <a href="#composite">composite</a> method and the CopyRed/Green/Blue/OpacityCompositeOp
        <a href="constants.html#CompositeOperator">CompositeOperator</a> enum values.
      </p>

      <h4>Magick API</h4>

      <p>CombineImages</p>
    </div>

    <div class="sig">
      <h3 id="constitute">constitute</h3>

      <p>
        Image.constitute(<span class="arg">width</span>, <span class="arg">height</span>, <span class="arg">map</span>, <span class="arg">pixels</span>) -&gt;
        <em>image</em>
      </p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>
        Creates an image from an array of pixels. This method is the reverse of
        <a href="#dispatch"><code>dispatch</code></a
        >.
      </p>

      <h4>Arguments</h4>

      <dl>
        <dt>width</dt>

        <dd>The number of columns in the image</dd>

        <dt>height</dt>

        <dd>The number of rows in the image</dd>

        <dt>map</dt>

        <dd>
          A string describing
          <span class="imquote"
            >the expected ordering of the pixel array. It can be any combination or order of R = red, G = green, B = blue, A = alpha, C = cyan, Y = yellow, M =
            magenta, K = black, or I = intensity (for grayscale).</span
          >
        </dd>

        <dt>pixels</dt>

        <dd>
          The pixel data. The pixel data in the array must be stored in scanline order, left-to-right and top-to-bottom. The elements in the array must be
          either all <code>Integers</code> or all <code>Floats</code>. If the elements are <code>Integers</code>, the <code>Integers</code>
          must be in the range [0..QuantumRange]. If the elements are
          <code>Floats</code>, they must be in the range [0..1].
        </dd>
      </dl>

      <h4>Returns</h4>

      <p>An image constructed from the pixel data.</p>

      <h4>Example</h4>
      <pre>
image = Image.constitute(width, height, "RGB", pixels)
</pre
      >

      <h4>See also</h4>

      <p>
        <a href="image2.html#import_pixels"><code>import_pixels</code></a
        >, <a href="image3.html#store_pixels"><code>store_pixels</code></a>
      </p>

      <h4>Magick API</h4>

      <p>ConstituteImage</p>
    </div>

    <div class="sig">
      <h3 id="from_blob">from_blob</h3>

      <p>Image.from_blob(<span class="arg">string</span>) [ <span class="arg">{ optional arguments }</span> ] -&gt; <em>array</em></p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>Creates an array of images from a BLOB, that is, a <em>B</em>inary <em>L</em>arge <em>OB</em>ject. In RMagick, a BLOB is a string.</p>

      <h4>Arguments</h4>

      <p>
        A blob can be a string containing an image file such as a JPEG or GIF. The string can contain a multi-image file such as an animated GIF or a Photoshop
        image with multiple layers. A blob can also be one of the strings produced by <a href="image3.html#to_blob">to_blob</a>. Control the format of the
        created image(s) by setting additional <a href="info.html">Image::Info</a> attributes in the optional block argument.
      </p>

      <h4>Returns</h4>

      <p>An array of one or more images constructed from the BLOB.</p>

      <h4>Example</h4>

      <p>
        See <a href="image3.html#to_blob"><code>to_blob</code></a
        >.
      </p>

      <h4>Magick API</h4>

      <p>BlobToImage</p>
    </div>

    <div class="sig">
      <h3 id="new">new</h3>

      <p>
        Image.new(<span class="arg">columns</span>, <span class="arg">rows</span> [, <span class="arg">fill</span>]) [
        <span class="arg">{ optional arguments }</span> ] -&gt; <em>image</em>
      </p>
    </div>

    <div class="desc">
      <h4>Description</h4>
      Creates a new instance with the specified number of columns and rows. You can specify other arguments by setting
      <a href="info.html">Image::Info</a> attributes in the optional block. If the optional <span class="arg">fill</span>
      argument is not specified, the image is set to the background color.

      <h4>Arguments</h4>

      <dl>
        <dt>columns</dt>

        <dd>The number of columns</dd>

        <dt>rows</dt>

        <dd>The number of rows</dd>

        <dt>fill</dt>

        <dd>
          A <a href="struct.html#fill"><code>Fill</code></a> object
        </dd>
      </dl>

      <h4>Returns</h4>

      <p>A new image.</p>

      <h4>Example</h4>
      <pre>
img = Image.new(256, 64) { |options|
  options.background_color = 'red'
}
</pre
      >

      <h4>See also</h4>

      <p>
        <a href="ilist.html#new_image"><code>ImageList.new_image</code></a>
      </p>

      <h4>Magick API</h4>

      <p>AllocateImage</p>
    </div>

    <div class="sig">
      <h3 id="ping">ping</h3>

      <p>
        Image.ping(<span class="arg">filename</span>) [ <span class="arg">{ optional arguments }</span> ] -&gt; <em>array</em><br />
        Image.ping(<span class="arg">file</span>) [ <span class="arg">{ optional arguments }</span> ] -&gt; <em>array</em>
      </p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>
        Creates one or more images from the image file, omitting the pixel data. Only the attributes are stored in the images. This method is faster than
        <code><a href="#read">read</a></code> and uses less memory.
      </p>

      <h4>Arguments</h4>

      <p>
        An image file name or open file object. You can specify other arguments by setting <a href="info.html">Image::Info</a> attributes in the optional block.
      </p>

      <h4>Returns</h4>

      <p>An array containing 0 or more images.</p>

      <h4>Example</h4>
      <pre>
cheetah = Image.ping("Cheetah.jpg") &raquo;
 [Cheetah.jpg JPEG 1024x768 DirectClass 8-bit 101684b]
p cheetah[0].rows &raquo; 768
p cheetah[0].columns &raquo; 1024
</pre
      >

      <h4>See also</h4>

      <p>
        <a href="#read"><code>read</code></a>
      </p>

      <h4>Magick API</h4>

      <p>PingImage</p>
    </div>

    <div class="sig">
      <h3 id="read">read</h3>

      <p>
        Image.read(<span class="arg">filename</span>) [ <span class="arg">{ optional arguments }</span> ] -&gt; <em>array</em><br />
        Image.read(<span class="arg">file</span>) [ <span class="arg">{ optional arguments }</span> ] -&gt; <em>array</em>
      </p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>Reads all the images from the specified file.</p>

      <p>
        <span style="font-style: italic">Note:</span> Because an image file can contain multiple images or multiple image layers, <code>read</code> always
        returns an array containing 0 or more elements, one element for each image or image layer in the file.
      </p>

      <h4>Arguments</h4>

      <p>
        An image file name or open file object. You can specify other arguments by setting <a href="info.html">Image::Info</a> attributes in the optional block.
      </p>

      <h4>Returns</h4>

      <p>
        An array containing 0 or more Image objects. If the file is a multi-image file such as an animated GIF or a Photoshop PSD file with multiple layers, the
        array contains an Image object for each image or layer in the file.
      </p>

      <h4>Example</h4>
      <pre>
animated = Image.read("animated.gif") &raquo;
[animated.gif GIF 127x120+0+0 PseudoClass 256c 8-bit 54395b
animated.gif[1] GIF 127x120+0+0 PseudoClass 256c 8-bit 54395b,
animated.gif[2] GIF 127x120+0+0 PseudoClass 256c 8-bit 54395b]
</pre
      >

      <h4>See also</h4>

      <p>
        <a href="#ping"><code>ping</code></a>
      </p>

      <h4>Note</h4>

      <p>
        The read method does not accept a StringIO object. If you want to create an image from a string buffer, use
        <a href="image1.html#from_blob">from_blob</a>.
      </p>

      <h4>Magick API</h4>

      <p>ReadImage</p>
    </div>

    <div class="sig">
      <h3 id="read_inline">read_inline</h3>

      <p>Image.read_inline(<span class="arg">content</span>) [ <span class="arg">{ optional arguments }</span> ] -&gt; <em>array</em></p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>Converts a Base64-encoded image or multi-image sequence to an array of Image objects.</p>

      <h4>Arguments</h4>

      <p>
        A Base64-encoded string. Generally no optional arguments are required. If the image format cannot be deduced from the image data, you can use the
        <a href="info.html#format">format</a> attribute. If you want to extract a subset of an image sequence, see <a href="imusage.html#frames">here</a>.
      </p>

      <h4>Returns</h4>

      <p>
        An array containing 0 or more Image objects. If the content is a multi-image sequence such as an animated GIF or a Photoshop PSD file with multiple
        layers, the array contains an Image object for each image or layer in the file.
      </p>

      <h4>Example</h4>
      <pre>
content = "R0lGODlhnAEuAferAAAAAAcIBggJBgw..."
img = Image.read_inline(content)
</pre
      >

      <h4>See also</h4>

      <p>
        <a href="#read"><code>read</code></a>
      </p>
    </div>

    <h2 class="methods">instance methods</h2>

    <div class="sig">
      <h3 id="aref">[&nbsp;]</h3>

      <p>
        <span class="arg">img</span>[<span class="arg">key</span>] -&gt;
        <em>string</em>
      </p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>
        Returns the value of the image property identified by
        <span class="arg">key</span>. An image may have any number of properties. Each property is identified by a string (or symbol) key. The property value is
        a string. ImageMagick predefines some properties, including <code>Label</code>, <code>Comment</code>, <code>Signature</code>, and in some cases
        <code>EXIF</code>.
      </p>

      <h4>Arguments</h4>
      The key may be a <code>String</code> or a <code>Symbol</code>.

      <h4>Returns</h4>

      <p>The value of the property.</p>

      <h4>Example</h4>
      <pre>
 mom['Label'] = 'My Mother'
</pre
      >

      <h4>See also</h4>

      <p>
        <a href="#aset"><code>[ ]=</code></a
        >, <a href="image3.html#properties"><code>properties</code></a>
      </p>

      <h4>Magick API</h4>

      <p>GetImageAttribute</p>

      <h4>Note</h4>

      <p>
        ImageMagick calls properties "attributes." I use the word "properties" to reduce the confusion with image object attributes such as
        <code>rows</code> and <code>columns</code>.
      </p>
    </div>

    <div class="sig">
      <h3 id="aset">[&nbsp;]=</h3>

      <p><span class="arg">img</span>[<span class="arg">key</span>] = <span class="arg">string</span> -&gt; <em>self</em></p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>Sets the value of an image property. An image may have any number of properties.</p>

      <h4>Arguments</h4>
      The <span class="arg">key</span> may be a string or a symbol. The value can be any string.

      <h4>Returns</h4>
      <code>self</code>

      <h4>Example</h4>
      See <a href="javascript:popup('demo.rb.html')">demo.rb</a> for an example of the use of the Label property.

      <h4>See also</h4>

      <p>
        <a href="#aref">[<code>&nbsp;]</code></a
        >, <a href="image3.html#properties"><code>properties</code></a>
      </p>

      <h4>Magick API</h4>

      <p>SetImageAttribute</p>
    </div>

    <div class="sig">
      <h3 id="spaceship">&lt;=&gt;</h3>

      <p><span class="arg">img</span> &lt;=&gt; <span class="arg">other_image</span> -&gt; -1, 0, 1</p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>
        Compares two images and returns -1, 0, or 1 if
        <span class="arg">img</span> is less than, equal to, or greater than <span class="arg">other_image</span> as determined by comparing the signatures of
        the images. If one of the arguments is not an image, this method raises a TypeError exception (in Ruby 1.6) or returns <code>nil</code> (in Ruby 1.8)
      </p>

      <p>
        In addition to &lt;=&gt;, <code>Image</code> mixes in the <code>Comparable</code> module, which defines the &lt;, &lt;=, == &gt;=, &gt;, and
        <code>between?</code> methods.
      </p>

      <p>
        The <code>difference</code> method compares images (for equality only) but also returns information about the amount two images differ, which may be
        more useful.
      </p>

      <h4>Returns</h4>

      <p>The value of <span class="arg">img</span>.<code>signature</code> &lt;=&gt; <span class="arg">other_image</span>.<code>signature</code>.</p>

      <h4>See also</h4>

      <p>
        <a href="image3.html#signature">signature</a>, <a href="#difference">difference</a>,
        <a href="#compare_channel">compare_channel</a>
      </p>

      <h4>Magick API</h4>

      <p>SignatureImage</p>
    </div>

    <div class="sig">
      <h3 id="adaptive_blur">adaptive_blur</h3>

      <p><span class="arg">img</span>.adaptive_blur(<span class="arg">radius</span>=0.0, <span class="arg">sigma</span>=1.0) -&gt; <em>image</em></p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>
        <span class="imquote">Adaptively blurs the image by blurring more intensely near image edges and less intensely far from edges.</span>
        The adaptive_blur method blurs
        <span class="imquote">the image with a Gaussian operator of the given</span>
        <span class="arg">radius</span>
        <span class="imquote">and standard deviation</span> (<span class="arg">sigma</span>). <span class="imquote">For reasonable results,</span>
        <span class="arg">radius</span>
        <span class="imquote">should be larger than</span>
        <span class="arg">sigma</span>. <span class="imquote">Use a</span>
        <span class="arg">radius</span>
        <span class="imquote">of 0 and adaptive_blur selects a suitable</span>
        <span class="arg">radius</span> <span class="imquote">for you.</span>
      </p>

      <h4>Arguments</h4>

      <dl>
        <dt>radius</dt>

        <dd>
          <span class="imquote">The radius of the Gaussian in pixels, not counting the center pixel.</span>
          The default is 0.0.
        </dd>

        <dt>sigma</dt>

        <dd>
          <span class="imquote">The standard deviation of the Laplacian, in pixels.</span>
          The default is 1.0.
        </dd>
      </dl>

      <h4>Returns</h4>

      <p>A new image</p>

      <h4>See also</h4>

      <p><a href="#adaptive_blur_channel">adaptive_blur_channel</a></p>

      <h4>Magick API</h4>

      <p>AdaptiveBlurImage</p>
    </div>

    <div class="sig">
      <h3 id="adaptive_blur_channel">adaptive_blur_channel</h3>

      <p>
        <span class="arg">img</span>.adaptive_blur(<span class="arg">radius</span>=0.0, <span class="arg">sigma</span>=1.0 [,<span class="arg">channel</span
        >...]) -&gt; <em>image</em>
      </p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>The same as <code>adaptive_blur</code> except only the specified channels are blurred.</p>

      <h4>Arguments</h4>

      <dl>
        <dt>radius</dt>

        <dd>
          <span class="imquote">The radius of the Gaussian in pixels, not counting the center pixel.</span>
          The default is 0.0.
        </dd>

        <dt>sigma</dt>

        <dd>
          <span class="imquote">The standard deviation of the Laplacian, in pixels.</span>
          The default is 1.0.
        </dd>

        <dt>channel...</dt>

        <dd>
          0 or more
          <a href="constants.html#ChannelType">ChannelType</a> arguments. If no channels are specified, blurs all the channels. Specifying no channel arguments
          has the same effect as the <code>adaptive_blur</code> method, above.
        </dd>
      </dl>

      <h4>Returns</h4>

      <p>A new image</p>

      <h4>See also</h4>

      <p><a href="#adaptive_blur">adaptive_blur</a></p>

      <h4>Magick API</h4>

      <p>AdaptiveBlurImageChannel</p>
    </div>

    <div class="sig">
      <h3 id="adaptive_resize">adaptive_resize</h3>

      <p>
        <span class="arg">img</span>.adaptive_resize(<span class="arg">new_width</span>, <span class="arg">new_height</span>) -&gt; <em>image</em><br />
        <span class="arg">img</span>.adaptive_resize(<span class="arg">scale_factor</span>) -&gt; <span class="arg">image</span>
      </p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>Resizes the image with data dependent triangulation.</p>

      <h4>Arguments</h4>

      <p>
        You can specify the new size in two ways. Either specify the new width and height explicitly, or specify a <em>scale factor</em>, a number that
        represents the percentage change.
      </p>

      <p>
        Use the <a href="#change_geometry">change_geometry</a> method to compute new dimensions for an image with constraints such as "maintain the current
        proportions."
      </p>

      <dl>
        <dt>new_width, new_height</dt>

        <dd>The desired width and height.</dd>

        <dt>scale_factor</dt>

        <dd>
          You can use this argument instead of specifying the desired width and height. The percentage size change. For example, 1.25 makes the new image 125%
          of the size of the receiver. The scale factor 0.5 makes the new image 50% of the size of the receiver.
        </dd>
      </dl>

      <h4>Returns</h4>

      <p>A new image</p>

      <h4>See also</h4>

      <p><a href="image3.html#resize">resize</a></p>

      <h4>Magick API</h4>

      <p>AdaptiveResizeImage</p>
    </div>

    <div class="sig">
      <h3 id="adaptive_sharpen">adaptive_sharpen</h3>

      <p><span class="arg">img</span>.adaptive_sharpen(<span class="arg">radius</span>=0.0, <span class="arg">sigma</span>=1.0) -&gt; <em>image</em></p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>
        <span class="imquote">Adaptively sharpens the image by sharpening more intensely near image edges and less intensely far from edges.</span>
        The adaptive_sharpen method sharpens
        <span class="imquote">the image with a Gaussian operator of the given</span>
        <span class="arg">radius</span>
        <span class="imquote">and standard deviation</span> (<span class="arg">sigma</span>). <span class="imquote">For reasonable results,</span>
        <span class="arg">radius</span>
        <span class="imquote">should be larger than</span>
        <span class="arg">sigma</span>. <span class="imquote">Use a</span>
        <span class="arg">radius</span>
        <span class="imquote">of 0 and adaptive_sharpen selects a suitable</span>
        <span class="arg">radius</span> <span class="imquote">for you.</span>
      </p>

      <h4>Arguments</h4>

      <dl>
        <dt>radius</dt>

        <dd>
          <span class="imquote">The radius of the Gaussian in pixels, not counting the center pixel.</span>
          The default is 0.0.
        </dd>

        <dt>sigma</dt>

        <dd>
          <span class="imquote">The standard deviation of the Laplacian, in pixels.</span>
          The default is 1.0.
        </dd>
      </dl>

      <h4>Returns</h4>

      <p>A new image</p>

      <h4>See also</h4>

      <p><a href="#adaptive_sharpen_channel">adaptive_sharpen_channel</a></p>

      <h4>Magick API</h4>

      <p>AdaptiveSharpenImage</p>
    </div>

    <div class="sig">
      <h3 id="adaptive_sharpen_channel">adaptive_sharpen_channel</h3>

      <p>
        <span class="arg">img</span>.adaptive_sharpen(<span class="arg">radius</span>=0.0, <span class="arg">sigma</span>=1.0 [,<span class="arg">channel</span
        >...]) -&gt; <em>image</em>
      </p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>The same as <code>adaptive_sharpen</code> except only the specified channels are sharpened.</p>

      <h4>Arguments</h4>

      <dl>
        <dt>radius</dt>

        <dd>
          <span class="imquote">The radius of the Gaussian in pixels, not counting the center pixel.</span>
          The default is 0.0.
        </dd>

        <dt>sigma</dt>

        <dd>
          <span class="imquote">The standard deviation of the Laplacian, in pixels.</span>
          The default is 1.0.
        </dd>

        <dt>channel...</dt>

        <dd>
          0 or more
          <a href="constants.html#ChannelType">ChannelType</a> arguments. If no channels are specified, sharpens all the channels. Specifying no channel
          arguments has the same effect as the <code>adaptive_sharpen</code> method, above.
        </dd>
      </dl>

      <h4>Returns</h4>

      <p>A new image</p>

      <h4>See also</h4>

      <p><a href="#adaptive_sharpen">adaptive_sharpen</a></p>

      <h4>Magick API</h4>

      <p>AdaptiveSharpenImageChannel</p>
    </div>

    <div class="sig">
      <h3 id="adaptive_threshold">adaptive_threshold</h3>

      <p>
        <span class="arg">img</span>.adaptive_threshold(<span class="arg">width</span>=3, <span class="arg">height</span>=3, <span class="arg">offset</span>=0)
        -&gt; <em>image</em>
      </p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p class="imquote">
        Selects an individual threshold for each pixel based on the range of intensity values in its local neighborhood. This allows for thresholding of an
        image whose global intensity histogram doesn't contain distinctive peaks.
      </p>

      <h4>Arguments</h4>

      <dl>
        <dt>width, height</dt>

        <dd>define the width and height of the local neighborhood</dd>

        <dt>offset</dt>

        <dd>constant to subtract from pixel neighborhood mean</dd>
      </dl>

      <h4>Returns</h4>

      <p>A new image</p>

      <h4>Example</h4>

      <p class="rollover">
        <a href="javascript:popup('adaptive_threshold.rb.html')"
          ><img
            src="ex/adaptive_threshold.jpg"
            onmouseover="this.src='ex/images/Flower_Hat.jpg'"
            onmouseout="this.src='ex/adaptive_threshold.jpg'"
            alt="adaptive_threshold example"
            title="Click to see the example script"
        /></a>
        <img src="ex/images/spin.gif" alt="" class="spin" title="Mouse over the example to see the original image" />
      </p>

      <h4>See also</h4>

      <p>
        <a href="#bilevel_channel">bilevel_channel</a>, <a href="image3.html#random_threshold_channel">random_threshold_channel</a>,
        <a href="image3.html#threshold">threshold</a>
      </p>

      <h4>Magick API</h4>

      <p>AdaptiveThresholdImage</p>
    </div>

    <div class="sig">
      <h3 id="add_compose_mask">add_compose_mask</h3>

      <p><span class="arg">img</span>.add_compose_mask(<span class="arg">mask</span>) -&gt; <em>self</em></p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>
        Associates a mask with an image that will be used as the destination image in a <a href="#composite">composite</a> operation. The areas of the
        destination image that are masked by white pixels will be modified by the <a href="#composite">composite</a> method, while areas masked by black pixels
        are unchanged.
      </p>

      <p>
        See
        <a href="https://www.imagemagick.org/Usage/compose/#mask">Using a Compose Mask to Limit the Composed Area</a>
        in Anthony Thyssen's
        <a href="https://www.imagemagick.org/Usage/">Examples of ImageMagick Usage</a>.
      </p>

      <h4>Arguments</h4>

      <p>The mask image must have the same dimensions as the destination image.</p>

      <h4>Returns</h4>

      <p>self</p>

      <h4>Example</h4>

      <div>
        <table summary="compose_mask example">
          <tr>
            <td>
              <a href="javascript:add_popup('compose_mask.rb.html')"
                ><img
                  src="ex/images/Flower_Hat.jpg"
                  width="100"
                  height="125"
                  alt="Source image for add_compose_mask example"
                  title="Click to see the example script"
              /></a>
            </td>

            <td>
              <a href="javascript:add_popup('compose_mask.rb.html')"
                ><img
                  src="ex/compose_mask_source.gif"
                  width="100"
                  height="125"
                  alt="Background image for add_compose_mask example"
                  title="Click to see the example script"
              /></a>
            </td>

            <td>
              <a href="javascript:add_popup('compose_mask.rb.html')"
                ><img src="ex/compose_mask.gif" width="100" height="125" alt="Mask image for compose_mask example" title="Click to see the example script"
              /></a>
            </td>

            <td>
              <a href="javascript:add_popup('compose_mask.rb.html')"
                ><img
                  src="ex/compose_mask_example.jpg"
                  width="93"
                  height="125"
                  alt="Result image for compose_mask example"
                  title="Click to see the example script"
              /></a>
            </td>
          </tr>

          <tr>
            <td align="center">Background</td>

            <td align="center">Source</td>

            <td align="center">Mask</td>

            <td align="center">Result</td>
          </tr>
        </table>
      </div>

      <h4>See also</h4>

      <p>
        <a href="#composite">composite</a>,
        <a href="#delete_compose_mask">delete_compose_mask</a>
      </p>

      <h4>Notes</h4>

      <p>This method uses a <em>copy</em> of the argument as the mask. If you change the mask image you must call this method again to update the mask.</p>

      <h4>Magick API</h4>

      <p>SetImageMask</p>
    </div>

    <div class="sig">
      <h3 id="add_noise">add_noise</h3>

      <p><span class="arg">img</span>.add_noise(<span class="arg">noise_type</span>) -&gt; <em>image</em></p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>
        Adds random noise to the image. The amount of time
        <code>add_noise</code> requires depends on the NoiseType argument.
      </p>

      <h4>Arguments</h4>

      <p>A <a href="constants.html#NoiseType">NoiseType</a> value.</p>

      <h4>Returns</h4>

      <p>A new image</p>

      <h4>Example</h4>

      <div class="noise_example_wrapper">
        <a href="javascript:popup('add_noise.rb.html')"
          ><img src="ex/images/Flower_Hat.jpg" alt="add_noise example" id="add_noise_example" title="Click to see the example script"
        /></a>

        <p>Click the NoiseType to see the effect.</p>

        <ul>
          <li><a href="javascript:show_noise(null)">No noise</a></li>

          <li>
            <a href="javascript:show_noise('UniformNoise');">UniformNoise</a>
          </li>

          <li>
            <a href="javascript:show_noise('GaussianNoise');">GaussianNoise</a>
          </li>

          <li>
            <a href="javascript:show_noise('MultiplicativeGaussianNoise');">MultiplicativeGaussianNoise</a>
          </li>

          <li>
            <a href="javascript:show_noise('ImpulseNoise');">ImpulseNoise</a>
          </li>

          <li>
            <a href="javascript:show_noise('LaplacianNoise');">LaplacianNoise</a>
          </li>

          <li>
            <a href="javascript:show_noise('PoissonNoise');">PoissonNoise</a>
          </li>
        </ul>
      </div>

      <div style="clear: both"></div>

      <h4>Notes</h4>

      <p>The RandomNoise type was added in ImageMagick 6.3.5.</p>

      <h4>Magick API</h4>

      <p>AddNoiseImage</p>

      <h4>See also</h4>

      <p><a href="#add_noise_channel">add_noise_channel</a></p>
    </div>

    <div class="sig">
      <h3 id="add_profile">add_profile</h3>

      <p><span class="arg">img</span>.add_profile(<span class="arg">filename</span>) -&gt; <span class="arg">self</span></p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>Adds an ICC (a.k.a. ICM), IPTC, or generic profile. If the file contains more than one profile all the profiles are added.</p>

      <h4>Arguments</h4>

      <p>The filename of a file containing the profile.</p>

      <h4>Returns</h4>

      <p>self</p>

      <h4>Example</h4>
      <pre>
    img.add_profile('my_cmyk.icm')
</pre
      >

      <h4>See also</h4>

      <p>
        The <a href="imageattrs.html#iptc_profile">iptc_profile</a> and <a href="imageattrs.html#color_profile">color_profile</a> attributes provide very
        similar functionality, except that these attributes accept the profile data in the form of a string. The
        <a href="image3.html#profile_bang">profile!</a> method can also be used to add a profile. The type of profile must be specified and the profile data
        must be in the form of a string. Also see <a href="#delete_profile">delete_profile</a> and <a href="image2.html#each_profile">each_profile</a>.
      </p>

      <h4>Magick API</h4>

      <p>ProfileImage</p>
    </div>

    <div class="sig">
      <h3 id="add_noise_channel">add_noise_channel</h3>

      <p><span class="arg">img</span>.add_noise_channel(<span class="arg">noise_type</span> [,<span class="arg">channel</span>...]) -&gt; <em>image</em></p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>Adds random noise to the specified channel or channels in the image.</p>

      <h4>Arguments</h4>

      <dl>
        <dt>noise_type</dt>

        <dd>A <a href="constants.html#NoiseType">NoiseType</a> value.</dd>

        <dt>channel...</dt>

        <dd>
          0 or more
          <a href="constants.html#ChannelType">ChannelType</a> arguments. If no channels are specified, adds noise to all the channels. Specifying no channel
          arguments has the same effect as the <code>add_noise</code> method, above.
        </dd>
      </dl>

      <h4>Returns</h4>

      <p>A new image</p>

      <h4>Magick API</h4>

      <p>AddNoiseImageChannel</p>

      <h4>See also</h4>

      <p><a href="#add_noise">add_noise</a></p>
    </div>

    <div class="sig">
      <h3 id="affine_transform">affine_transform</h3>

      <p><span class="arg">img</span>.affine_transform(<span class="arg">matrix</span>) -&gt; <em>image</em></p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>Transforms the image as specified by the affine matrix.</p>

      <p>
        See
        <a href="https://www.w3.org/TR/SVG/coords.html#EstablishingANewUserSpace"> <b>Coordinate system transformations</b></a>
        in the
        <cite>Scalable Vector Graphics (SVG) 1.0 Specification</cite>
        for more information about transformation matrices.
      </p>

      <h4>Arguments</h4>

      <p>
        An
        <a href="struct.html#AffineMatrix"><code>AffineMatrix</code></a> object.
      </p>

      <h4>Returns</h4>

      <p>A new image</p>

      <h4>Example</h4>

      <p>The affine matrix in this example skews the receiver by &pi;/6 radians along both axes.</p>

      <p class="rollover">
        <a href="javascript:popup('affine_transform.rb.html')"
          ><img
            onmouseover="this.src='ex/images/Flower_Hat.jpg'"
            onmouseout="this.src='ex/affine_transform.jpg'"
            src="ex/affine_transform.jpg"
            alt="affine_transform example"
            title="Click to see the example script"
        /></a>
        <img src="ex/images/spin.gif" alt="" class="spin" style="left: 235px" title="Mouse over the example to see the original image" />
      </p>

      <h4>See also</h4>

      <p>
        <a href="image3.html#rotate">rotate</a>,
        <a href="image3.html#shear">shear</a>
      </p>

      <h4>Magick API</h4>

      <p>AffineTransformImage</p>
    </div>

    <div class="sig">
      <h3 id="alpha">alpha</h3>

      <p>
        <span class="arg">img</span>.alpha(<span class="arg">type</span>) -&gt;
        <em>type</em>
      </p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>Set a flag to indicate whether or not to use alpha channel data.</p>

      <h4>Arguments</h4>

      <p>One of the following values of the AlphaChannelOption enumeration:</p>

      <dl>
        <dt>OnAlphaChannel</dt>

        <dd class="imquote">
          Enable the images use of transparency. If transparency data did not exist, allocate the data and set to opaque. If the image previously had
          transparency data, the data is again enable as it was when turned off. The transparency data is not changed or modified in any way.
        </dd>

        <dt>BackgroundAlphaChannel</dt>

        <dd>Set fully transparent pixels to the background color. (Available in IM 6.5.2-5.)</dd>

        <dt>CopyAlphaChannel</dt>

        <dd class="imquote">
          Turns on the alpha/matte channel, then copies the gray-scale intensity of the image, as an alpha mask, into the alpha channel, converting a gray-scale
          mask into a transparent shaped image ready to be colored appropriately. The color channels are not modified.
        </dd>

        <dt>OffAlphaChannel</dt>

        <dd class="imquote">
          Disables the image's transparency channel. Does not delete or change the existing data, just turns of the use of that data. This is the same as
          assigning false to the old matte= attribute.
        </dd>

        <dt>ExtractAlphaChannel</dt>

        <dd>
          Creates a grayscale mask of the image's shape by copying the alpha channel values into all the color channels, and then turning off the image's
          transparency. The inverse of CopyAlphaChannel
        </dd>

        <dt>OpaqueAlphaChannel</dt>

        <dd class="imquote">Turns on the alpha/matte channel and forces it to be fully opaque.</dd>

        <dt>SetAlphaChannel</dt>

        <dd class="imquote">
          Turns on the alpha/matte channel and if it was previously turned off resets the channel to opaque. If the image already had the alpha channel turned
          on, it will have no effect.
        </dd>

        <dt>ShapeAlphaChannel</dt>

        <dd class="imquote">As CopyAlphaChannel but also colors the resulting shape mask with the current background color.</dd>

        <dt>TransparentAlphaChannel</dt>

        <dd class="imquote">
          Turns on the alpha/matte channel and forces it to be fully transparent. This effectivally creates a transparent image the same size as the original,
          with all its meta-data still attached.
        </dd>
      </dl>

      <h4>Returns</h4>

      <p>The argument.</p>

      <h4>See also</h4>

      <p><a href="#alpha_q">alpha?</a></p>

      <h4>Notes</h4>

      <p>Available in ImageMagick 6.3.5 and later.</p>

      <h4>Magick API</h4>

      <p>SetImageAlphaChannel</p>
    </div>

    <div class="sig">
      <h3 id="alpha_q">alpha?</h3>

      <p>
        <span class="arg">img</span>.alpha? -&gt; <code>true</code> or
        <code>false</code>
      </p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>Returns <code>true</code> if the alpha channel will be used, <code>false</code> otherwise.</p>

      <h4>See also</h4>

      <p><a href="#alpha">alpha</a></p>

      <h4>Magick API</h4>

      <p>GetImageAlphaChannel</p>
    </div>

    <div class="sig">
      <h3 id="annotate">annotate</h3>

      <p>
        <span class="arg">img.</span>annotate(<span class="arg">draw, width, height, x, y, text</span>)
        <span class="arg">[&nbsp;{ additional parameters }&nbsp;]</span> -&gt;
        <em>self</em>
      </p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>
        This is the same method as the <code>annotate</code> method in the Draw class, except that the first argument is a Draw object. Refer to the
        documentation for <a href="draw.html#annotate">Draw#annotate</a> for more information. Some users feel like <code>annotate</code> is better placed in
        Image than in Draw. Okay, here it is!
      </p>

      <h4>Returns</h4>

      <p>self</p>
    </div>

    <div class="sig">
      <h3 id="auto_gamma_channel">auto_gamma_channel</h3>

      <p><span class="arg">img</span>.auto_gamma_channel([<span class="arg">channel</span>...]) -&gt; <em>image</em></p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>"Automagically" adjust the gamma level of an image.</p>

      <h4>Arguments</h4>

      <dl>
        <dt>channel...</dt>

        <dd>
          0 or more
          <a href="constants.html#ChannelType">ChannelType</a> arguments. If no channels are specified, automagically adjusts the gamma level of all the
          channels.
        </dd>
      </dl>

      <h4>Returns</h4>

      <p>A new image</p>
    </div>

    <div class="sig">
      <h3 id="auto_level_channel">auto_level_channel</h3>

      <p><span class="arg">img</span>.auto_level_channel([<span class="arg">channel</span>...]) -&gt; <em>image</em></p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>"Automagically" adjust the color levels of an image.</p>

      <h4>Arguments</h4>

      <dl>
        <dt>channel...</dt>

        <dd>
          0 or more
          <a href="constants.html#ChannelType">ChannelType</a> arguments. If no channels are specified, automagically adjusts the color level of all the
          channels.
        </dd>
      </dl>

      <h4>Returns</h4>

      <p>A new image</p>
    </div>

    <div class="sig">
      <h3 id="auto_orient">auto_orient</h3>

      <p><span class="arg">img</span>.auto_orient -&gt; <em>image</em></p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>
        Rotates or flips the image based on the image's EXIF orientation tag. Note that only some models of modern digital cameras can tag an image with the
        orientation. If the image does not have an orientation tag, or the image is already properly oriented, then
        <code>auto_orient</code> returns an exact copy of the image.
      </p>

      <h4>Returns</h4>

      <p>A new image</p>

      <h4>See also</h4>

      <p><a href="#auto_orient_bang">auto_orient!</a></p>

      <h4>Magick API</h4>

      <p>FlipImage, FlopImage, RotateImage, TransposeImage, TransverseImage</p>
    </div>

    <div class="sig">
      <h3 id="auto_orient_bang">auto_orient!</h3>

      <p><span class="arg">img</span>.auto_orient! -&gt; <em>self</em></p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>
        Rotates or flips the image based on the image's EXIF orientation tag. Note that only some models of modern digital cameras can tag an image with the
        orientation. If the image does not have an orientation tag, or the image is already properly oriented, then
        <code>auto_orient!</code> returns <code>nil</code>.
      </p>

      <h4>Returns</h4>

      <p>self. or <code>nil</code> if the image is already properly oriented</p>

      <h4>See also</h4>

      <p><a href="#auto_orient">auto_orient</a></p>
    </div>

    <div class="sig">
      <h3 id="bilevel_channel">bilevel_channel</h3>

      <p><span class="arg">img</span>.bilevel_channel(<span class="arg">threshold</span> [,<span class="arg">channel...</span>]) -&gt; <em>image</em></p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p class="imquote">Changes the value of individual pixels based on the intensity of each pixel channel. The result is a high-contrast image.</p>

      <h4>Arguments</h4>

      <dl>
        <dt>threshold</dt>

        <dd>The threshold value, a number between 0 and QuantumRange.</dd>

        <dt>channel...</dt>

        <dd>
          0 or more
          <a href="constants.html#ChannelType">ChannelType</a> arguments. If no channels are specified, all the channels are thresholded.
        </dd>
      </dl>

      <h4>Returns</h4>

      <p>A new image</p>

      <h4>Example</h4>

      <p><code>bilevel_channel(2*QuantumRange/3, RedChannel)</code></p>

      <p class="rollover">
        <a href="javascript:popup('bilevel_channel.rb.html')"
          ><img
            onmouseover="this.src='ex/images/Flower_Hat.jpg'"
            onmouseout="this.src='ex/bilevel_channel.jpg'"
            src="ex/bilevel_channel.jpg"
            alt="bilevel_channel example"
            title="Click to see the example script"
        /></a>
        <img src="ex/images/spin.gif" alt="" class="spin" title="Mouse over the example to see the original image" />
      </p>

      <h4>See also</h4>

      <p>
        <a href="#adaptive_threshold">adaptive_threshold</a>,
        <a href="image3.html#random_threshold_channel">random_threshold_channel</a>
      </p>

      <h4>Magick API</h4>

      <p>BilevelImageChannel</p>
    </div>

    <div class="sig">
      <h3 id="black_threshold">black_threshold</h3>

      <p>
        <span class="arg">img</span>.black_threshold(<span class="arg">red_channel</span> [, <span class="arg">green_channel</span> [,
        <span class="arg">blue_channel</span> [, <span class="arg">opacity_channel</span>]]]) -&gt; <em>image</em>
      </p>
    </div>
    <!-- this example is larger than normal -->

    <div class="desc">
      <h4>Description</h4>

      <p class="imquote">Forces all pixels below the threshold into black while leaving all pixels above the threshold unchanged.</p>

      <h4>Arguments</h4>

      <p>
        Each channel argument is a number between 0 and QuantumRange. All arguments except the first may be omitted. If the
        <span class="arg">green_channel</span> or <span class="arg">blue_channel</span> argument is omitted, the default value is the
        <span class="arg">red_channel</span> value. If the <span class="arg">opacity_channel</span> argument is omitted, the default value is
        <a href="constants.html#Opacity">OpaqueOpacity</a>.
      </p>

      <h4>Returns</h4>

      <p>A new image</p>

      <h4>See also</h4>

      <p>
        <a href="image3.html#white_threshold">white_threshold</a>,
        <a href="#bilevel_channel">bilevel_channel</a>
      </p>

      <h4>Magick API</h4>

      <p>BlackThresholdImage</p>
    </div>

    <div class="sig">
      <h3 id="blend">blend</h3>

      <p>
        <span class="arg">img</span>.blend(<span class="arg">overlay</span>, <span class="arg">src_percentage</span>, <span class="arg">dst_percentage</span>,
        <span class="arg">x_offset</span>=0, <span class="arg">y_offset</span>=0) -&gt; <em>image</em><br />
        <span class="arg">img</span>.blend(<span class="arg">overlay</span>, <span class="arg">src_percentage</span>, <span class="arg">dst_percentage</span>,
        <span class="arg">gravity</span>, <span class="arg">x_offset</span>=0, <span class="arg">y_offset</span>=0) -&gt; <em>image</em>
      </p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>
        Adds the <span class="arg">overlay</span> image to the target image according to <span class="arg">src_percent</span> and
        <span class="arg">dst_percent</span>.
      </p>

      <p>
        This method corresponds to the -blend option of ImageMagick's
        <code>composite</code> command.
      </p>

      <h4>Arguments</h4>

      <dl>
        <dt>overlay</dt>

        <dd>The source image for the composite operation. Either an imagelist or an image. If an imagelist, uses the current image.</dd>

        <dt>src_percentage</dt>

        <dd>
          Either a non-negative number a string in the form "NN%". If
          <span class="arg">src_percentage</span> is a number it is interpreted as a percentage. Both 0.25 and "25%" mean 25%. This argument is required.
        </dd>

        <dt>dst_percentage</dt>

        <dd>
          Either a non-negative number a string in the form "NN%". If
          <span class="arg">src_percentage</span> is a number it is interpreted as a percentage. Both 0.25 and "25%" mean 25%. This argument may omitted if no
          other arguments follow it. In this case the default is 100%-<span class="arg">src_percentage</span>.
        </dd>
      </dl>

      <p>
        The <code>blend</code> method can be called with or without a <span class="arg">gravity</span> argument. The <span class="arg">gravity</span>,
        <span class="arg">x_offset</span>, and <span class="arg">y_offset</span> arguments are described in the documentation for
        <a href="image3.html#watermark">watermark</a>.
      </p>

      <h4>Example</h4>

      <p>
        See
        <a href="https://www.imagemagick.org/Usage/compose/#blend"> "Blend Two Images Together"</a>.
      </p>

      <h4>Returns</h4>

      <p>A new image</p>

      <h4>See also</h4>

      <p><a href="#dissolve">dissolve</a>, <a href="#composite">composite</a></p>
    </div>

    <div class="sig">
      <h3 id="blue_shift">blue_shift</h3>

      <p><span class="arg">img</span>.blue_shift(<span class="arg">factor</span>=1.5) -&gt; <em>image</em></p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p class="imquote">Simulate a scene at nighttime in the moonlight.</p>

      <h4>Arguments</h4>

      <dl>
        <dt>factor</dt>

        <dd>Larger values increase the effect. The default is 1.5.</dd>
      </dl>

      <h4>Returns</h4>

      <p>A new image</p>

      <h4>Notes</h4>

      <p>Available in ImageMagick 6.5.4-3 and later.</p>

      <h4>Magick API</h4>

      <p>BlueShiftImage</p>
    </div>

    <div class="sig">
      <h3 id="blur_channel">blur_channel</h3>

      <p>
        <span class="arg">img</span>.blur_channel(<span class="arg">radius=0.0</span>, <span class="arg">sigma=1.0</span
        ><span class="arg">[, channel...]]</span>) -&gt; <em>image</em>
      </p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>
        Blurs the specified channel.
        <span class="imquote"
          >We convolve the image with a Gaussian operator of the given radius and standard deviation (sigma) . The <code>blur_channel</code> method differs from
          <a href="image2.html#gaussian_blur_channel">gaussian_blur_channel</a>
          in that it uses a separable kernel which is faster but mathematically equivalent to the non-separable kernel.</span
        >
      </p>

      <h4>Arguments</h4>

      <p class="imquote">
        For reasonable results, the <span class="arg">radius</span> should be larger than <span class="arg">sigma</span>. Use a radius of 0 and
        <code>blur_channel</code> selects a suitable radius for you.
      </p>

      <dl>
        <dt>channel...</dt>

        <dd>
          One or more
          <a href="constants.html#ChannelType">ChannelType</a> values. If none are specified, the red, green, and blue channels are blurred. This is the
          equivalent of <a href="#blur_image">blur_image</a>.
        </dd>
      </dl>

      <h4>Returns</h4>

      <p>A new image</p>

      <h4>See also</h4>

      <p>
        <a href="#blur_image">blur_image</a>, <a href="image2.html#gaussian_blur_channel">gaussian_blur_channel</a>,
        <a href="image2.html#motion_blur">motion_blur</a>, <a href="image3.html#radial_blur">radial_blur</a>,
        <a href="image3.html#selective_blur_channel">selective_blur_channel</a>
      </p>

      <h4>Magick API</h4>

      <p>BlurImageChannel</p>
    </div>

    <div class="sig">
      <h3 id="blur_image">blur_image</h3>

      <p><span class="arg">img</span>.blur_image(<span class="arg">radius</span>=0.0, <span class="arg">sigma</span>=1.0) -&gt; <em>image</em></p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>
        Blurs the image.
        <span class="imquote">We convolve the image with a Gaussian operator of the given radius and standard deviation (sigma).</span>
      </p>

      <h4>Arguments</h4>

      <p class="imquote">
        For reasonable results, the <span class="arg">radius</span> should be larger than <span class="arg">sigma</span>. Use a
        <span class="arg">radius</span> of 0 and <code>blur_image</code> selects a suitable <span class="arg">radius</span> for you.
      </p>

      <h4>Returns</h4>

      <p>A new image.</p>

      <h4>Example</h4>

      <p class="rollover">
        <a href="javascript:popup('blur_image.rb.html')"
          ><img
            onmouseover="this.src='ex/images/Flower_Hat.jpg'"
            onmouseout="this.src='ex/blur_image.jpg'"
            src="ex/blur_image.jpg"
            alt="blur_image example"
            title="Click to see the example script"
        /></a>
        <img src="ex/images/spin.gif" alt="" class="spin" title="Mouse over the example to see the original image" />
      </p>

      <h4>See also</h4>

      <p>
        <a href="#blur_channel">blur_channel</a>, <a href="image2.html#gaussian_blur">gaussian_blur</a>, <a href="image2.html#motion_blur">motion_blur</a>,
        <a href="image3.html#radial_blur">radial_blur</a>,
        <a href="image3.html#selective_blur_channel">selective_blur_channel</a>
      </p>

      <h4>Magick API</h4>

      <p>BlurImage</p>
    </div>

    <div class="sig">
      <h3 id="border">border</h3>

      <p>
        <span class="arg">img</span>.border(<span class="arg">width</span>, <span class="arg">height</span>, <span class="arg">color</span>) -&gt;
        <em>image</em>
      </p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>Add a border around the image.</p>

      <h4>Arguments</h4>

      <dl>
        <dt>width</dt>

        <dd>Border width in pixels</dd>

        <dt>height</dt>

        <dd>Border height in pixels</dd>

        <dt>color</dt>

        <dd>
          Border color. Use a
          <a href="imusage.html#color_names">named color</a> or a <a href="struct.html#Pixel">pixel</a> object.
        </dd>
      </dl>

      <h4>Returns</h4>

      <p>A new image</p>

      <h4>Example</h4>

      <p class="rollover">
        <a href="javascript:popup('border.rb.html')"
          ><img
            style="padding: 10px; display: none"
            id="borderless"
            onmouseout="this.style.display='none'; bordered.style.display='';"
            src="ex/images/Flower_Hat.jpg"
            alt="border example"
            title="Click to see the example script" />
          <img id="bordered" onmouseover="this.style.display='none'; borderless.style.display='';" src="ex/border.jpg" alt="border example" /></a
        ><img src="ex/images/spin.gif" alt="" class="spin" style="left: 224px" title="Mouse over the example to see the original image" />
      </p>

      <h4>See also</h4>

      <p>
        <a href="#border_bang">border!</a>,
        <a href="image2.html#frame">frame</a>
      </p>

      <h4>Magick API</h4>

      <p>BorderImage</p>
    </div>

    <div class="sig">
      <h3 id="border_bang">border!</h3>

      <p>
        <span class="arg">img</span>.border!(<span class="arg">width</span>, <span class="arg">height</span>, <span class="arg">color</span>) -&gt;
        <em>self</em>
      </p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>In-place form of <a href="#border">border</a></p>

      <h4>Returns</h4>

      <p>self</p>
    </div>

    <div class="sig">
      <h3 id="bounding_box">bounding_box</h3>

      <p><span class="arg">img</span>.bounding_box -&gt; <em>rectangle</em></p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>
        The image's <em>bounding box</em>. The bounding box is the rectangle that encloses all the pixels not in the border color. Uses the current
        <a href="imageattrs.html#fuzz">fuzz</a> value.
      </p>

      <h4>Returns</h4>
      A <a href="struct.html#Rectangle">Rectangle</a>
      object.

      <h4>Example</h4>

      <p>
        In this example, the bounding box is the gray square enclosing the blue circle. (The coordinates and red circles were added after the bounding box was
        computed.)
      </p>

      <p>
        <a href="javascript:popup('bounding_box.rb.html')"
          ><img src="ex/bounding_box.gif" alt="ex/bounding_box.rb" title="Click to see the example script"
        /></a>
      </p>
    </div>

    <div class="sig">
      <h3 id="change_geometry">change_geometry</h3>

      <p>
        <span class="arg">img</span>.change_geometry(<span class="arg">string</span>) {|cols,rows,image| <span class="arg">block</span>} -&gt;
        <em>??? (see Returns)</em><br />
        <span class="arg">img.change_geometry</span>(<span class="arg">geometry</span>) {|cols,rows,image| <span class="arg">block</span>} -&gt;
        <em>??? (see Returns)</em>
      </p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>
        The <code>change_geometry</code> method supports resizing a method by specifying constraints. For example, you can specify that the image should be
        resized such that the aspect ratio should be retained but the resulting image should be no larger than 640 pixels wide and 480 pixels tall.
      </p>

      <p>
        The argument may be either a
        <a href="imusage.html#geometry">geometry string</a> or a <a href="struct.html#Geometry">Geometry</a> object. <code>Change_geometry</code> yields to the
        block, passing new width and height values based on the argument with respect to <code>self</code>. The return value is the return value of the block.
      </p>

      <h4>Arguments</h4>
      An <a href="imusage.html#geometry">geometry string</a> or a <code>Geometry</code> object

      <h4>Returns</h4>

      <p>The value returned by the block</p>

      <h4>Example</h4>
      <pre>
mona = Image.read('MonaLisa.jpg').first
mona.change_geometry!('320x240') { |cols, rows, img|
 img.resize!(cols, rows)
 }
</pre
      >

      <h4>Magick API</h4>

      <p>ParseSizeString</p>

      <h4>Note</h4>

      <p><code>change_geometry!</code> is an alias for <code>change_geometry</code>.</p>
    </div>

    <div class="sig">
      <h3 id="changed_q">changed?</h3>

      <p>
        <span class="arg">img</span>.changed? -&gt; <code>true</code> or
        <code>false</code>
      </p>
    </div>

    <div class="desc">
      <h4>Description</h4>
      Returns <code>true</code> if any pixel has been altered since the image was constituted.

      <h4>Magick API</h4>

      <p>IsTaintImage</p>
    </div>

    <div class="sig">
      <h3 id="channel">channel</h3>

      <p><span class="arg">img</span>.channel(<span class="arg">channel</span>) -&gt; <em>image</em></p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>
        Extracts a channel from the image.
        <span class="imquote">A channel is a particular color component of each pixel in the [image].</span>
      </p>

      <h4>Arguments</h4>

      <p>A <a href="constants.html#ChannelType">ChannelType</a> value.</p>

      <h4>Returns</h4>

      <p>
        An image in which the RGB values of all the pixels have been set to a gray corresponding to the specified channel value. For example, given a pixel in
        the original image with the value R=255, G=128, B=0 and the RedChannel argument, the equivalent pixel in the result image will have the value R=255,
        G=255, and B=255. For the BlueChannel argument, the pixel would have the value R=0, G=0, B=0.
      </p>

      <h4>Example</h4>

      <p>The channel image preserves the tone of the selected RGB component.</p>

      <p>
        <a href="javascript:popup('channel.rb.html')"><img src="ex/channel.jpg" alt="channel example" /></a>
      </p>

      <h4>Magick API</h4>

      <p>ChannelImage</p>
    </div>

    <div class="sig">
      <h3 id="channel_depth">channel_depth</h3>

      <p><span class="arg">img</span>.channel_depth([<span class="arg">channel</span>...]) -&gt; <em>number</em></p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>Returns the maximum depth for the specified channel or channels.</p>

      <h4>Arguments</h4>

      <dl>
        <dt>channel...</dt>

        <dd>
          Zero or more
          <a href="constants.html#ChannelType">ChannelType</a> values. If no arguments are specified, the default is all channels.
        </dd>
      </dl>

      <h4>Returns</h4>

      <p>The maximum depth</p>

      <h4>See also</h4>

      <p><a href="image3.html#set_channel_depth">set_channel_depth</a></p>

      <h4>Magick API</h4>

      <p>GetImageChannelDepth</p>
    </div>

    <div class="sig">
      <h3 id="channel_extrema">channel_extrema</h3>

      <p><span class="arg">img</span>.channel_extrema([<span class="arg">channel</span>...]) -&gt; <em>[number, number]</em></p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>Returns the minimum and maximum intensity values for the specified channel or channels.</p>

      <h4>Arguments</h4>

      <dl>
        <dt>channel...</dt>

        <dd>
          Zero or more
          <a href="constants.html#ChannelType">ChannelType</a> values. If no arguments are specified, the default is all channels.
        </dd>
      </dl>

      <h4>Returns</h4>

      <p>An array. The first element in the array is the minimum value. The second element is the maximum value.</p>

      <h4>Magick API</h4>

      <p>GetImageChannelExtrema</p>
    </div>

    <div class="sig">
      <h3 id="channel_mean">channel_mean</h3>

      <p><span class="arg">img</span>.channel_mean([<span class="arg">channel</span>...]) -&gt; <em>[number, number]</em></p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>Returns the mean and standard deviation values for the specified channel or channels.</p>

      <h4>Arguments</h4>

      <dl>
        <dt>channel...</dt>

        <dd>
          Zero or more
          <a href="constants.html#ChannelType">ChannelType</a> values. If no arguments are specified, the default is all channels.
        </dd>
      </dl>

      <h4>Returns</h4>

      <p>An array. The first element in the array is the mean value. The second element is the standard deviation.</p>

      <h4>Magick API</h4>

      <p>GetImageChannelMean</p>
    </div>

    <div class="sig">
      <h3 id="charcoal">charcoal</h3>

      <p><span class="arg">img</span>.charcoal(<span class="arg">radius</span>=0.0, <span class="arg">sigma</span>=1.0) -&gt; <em>image</em></p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>
        Adds a "charcoal" effect to the image. You can alter the intensity of the effect by changing the <span class="arg">radius</span> and
        <span class="arg">sigma</span> arguments.
      </p>

      <h4>Arguments</h4>

      <dl>
        <dt>radius</dt>

        <dd class="imquote">The radius of the pixel neighborhood.</dd>

        <dt>sigma</dt>

        <dd class="imquote">The standard deviation of the Gaussian, in pixels.</dd>
      </dl>

      <h4>Returns</h4>

      <p>A new image</p>

      <h4>Example</h4>

      <p class="rollover">
        <a href="javascript:popup('charcoal.rb.html')"
          ><img
            onmouseover="this.src='ex/images/Flower_Hat.jpg'"
            onmouseout="this.src='ex/charcoal.jpg'"
            src="ex/charcoal.jpg"
            alt="charcoal example"
            title="Click the image to see the example script"
        /></a>
        <img src="ex/images/spin.gif" alt="" class="spin" title="Mouse over the example to see the original image" />
      </p>

      <h4>Magick API</h4>

      <p>CharcoalImage</p>
    </div>

    <div class="sig">
      <h3 id="check_destroyed">check_destroyed</h3>

      <p><span class="arg">img</span>.check_destroyed -&gt; <code>nil</code></p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>Raises DestroyedImageError if the image has been destroyed. Returns nil otherwise.</p>

      <h4>See also</h4>

      <p>
        <a href="#destroy_bang">destroy!</a>,
        <a href="#destroyed_q">destroyed?</a>
      </p>
    </div>

    <div class="sig">
      <h3 id="chop">chop</h3>

      <p>
        <span class="arg">img</span>.chop(<span class="arg">x</span>, <span class="arg">y</span>, <span class="arg">width</span>,
        <span class="arg">height</span>) -&gt; <em>image</em>
      </p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>Removes the specified rectangle and collapses the rest of the image to fill the removed portion.</p>

      <h4>Arguments</h4>

      <dl>
        <dt>x</dt>

        <dd>The x offset of the rectangle from the upper-left corner of the image.</dd>

        <dt>y</dt>

        <dd>The y offset of the rectangle from the upper-left corner of the image.</dd>

        <dt>width</dt>

        <dd>The width of the rectangle.</dd>

        <dt>height</dt>

        <dd>The height of the rectangle.</dd>
      </dl>

      <h4>Returns</h4>

      <p>A new image</p>

      <h4>Example</h4>

      <p>The chop rectangle is highlighted in the "before" image. The result may seem counter-intuitive!</p>

      <p class="rollover">
        <a href="javascript:popup('chop.rb.html')"
          ><img
            onmouseover="this.src='ex/chop_before.jpg'"
            onmouseout="this.src='ex/chop_after.jpg'"
            src="ex/chop_after.jpg"
            alt="chop example"
            title="Click the image to see the example script"
        /></a>
        <img src="ex/images/spin.gif" alt="" class="spin" title="Mouse over the example to see the original image" />
      </p>

      <h4>See also</h4>

      <p><a href="#crop">crop</a></p>

      <h4>Magick API</h4>

      <p>ChopImage</p>
    </div>

    <div class="sig">
      <h3 id="clone">clone</h3>

      <p><span class="arg">img</span>.clone -&gt; <em>image</em></p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>Same as <a href="#dup">dup</a> except the frozen state of the original is propagated to the new copy.</p>

      <h4>Returns</h4>

      <p>A new image</p>

      <h4>See also</h4>

      <p><a href="#dup">dup</a></p>
    </div>

    <div class="sig">
      <h3 id="clut_channel">clut_channel</h3>

      <p><span class="arg">img</span>.clut(<span class="arg">clut_image</span> [, <span class="arg">channel...</span>]) -&gt; <em>self</em></p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>Replace the channel values in the target image with a lookup of its replacement value in an LUT gradient image.</p>

      <p class="imquote">
        The LUT image should be either a single row or column image of replacement colors. The lookup is controlled by the -interpolate setting, especially for
        an LUT which is not the full length needed by the IM installed Quality (Q) level. Good settings for this is the default 'bilinear' or 'bicubic'
        interpolation setting for a smooth color gradient, or 'integer' for a direct unsmoothed lookup of color values.
      </p>

      <p class="imquote">This method is especially suited to replacing a grayscale image with specific color gradient from the CLUT image.</p>

      <p class="imquote">
        Note that color replacements involving transparency (alpha/matte channel) will lookup the replacement alpha/matte value using the alpha/matte value of
        the original image. As such correct alpha channel lookup for a pure gray-scale original image will require a copy of that grayscale to be transferred
        into its alpha channel before applying the -clut operator.
      </p>

      <h4>Arguments</h4>

      <dl>
        <dt>clut_image</dt>

        <dd>
          The LUT gradient image. Specify which interpolation method to use by setting this image's
          <a href="imageattrs.html#pixel_interpolation_method">pixel_interpolation_method</a>
          attribute to a
          <a href="constants.html#PixelInterpolateMethod">PixelInterpolateMethod</a>
          value.
        </dd>

        <dt>channel...</dt>

        <dd>
          Limit which channels are modified by specifying one or more
          <a href="constants.html#ChannelType">ChannelType</a> values. Only these channels will be changed. If no channels are specified, all channels will be
          changed.
        </dd>
      </dl>

      <h4>Returns</h4>

      <p>self</p>

      <h4>See also</h4>

      <p>ImageMagick's -clut option.</p>
    </div>

    <div class="sig">
      <h3 id="color_fill_to_border">color_fill_to_border</h3>

      <p>
        <span class="arg">img</span>.color_fill_to_border(<span class="arg">x</span>, <span class="arg">y</span>, <span class="arg">fill_color</span>) -&gt;
        <em>image</em>
      </p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>Changes any pixel that is a neighbor of the target pixel and is not the border color to the fill color.</p>

      <h4>Arguments</h4>

      <dl>
        <dt>x, y</dt>

        <dd>The target pixel's location.</dd>

        <dt>fill_color</dt>

        <dd>
          The fill color. The fill color can be either color name or a
          <a href="struct.html#Pixel">Pixel</a> object.
        </dd>
      </dl>

      <h4>Returns</h4>

      <p>A new image</p>

      <h4>Example</h4>

      <p>
        In this example, the aquamarine fill starts at the center of the circle and fills to the black border. All non-black pixels are replaced by the fill
        color. Contrast the result of
        <code>color_fill_to_border</code> with that of <code>color_floodfill</code> example, below.
      </p>

      <p class="rollover">
        <a href="javascript:popup('color_fill_to_border.rb.html')"
          ><img
            onmouseover="this.src='ex/color_fill_to_border_before.gif'"
            onmouseout="this.src='ex/color_fill_to_border_after.gif'"
            src="ex/color_fill_to_border_after.gif"
            alt="color_fill_to_border example"
            title="Click the image to see the example script" /></a
        ><img
          src="ex/images/spin.gif"
          alt=""
          class="spin"
          style="margin-bottom: 182px; margin-left: 4px"
          title="Mouse over the example to see the original image"
        />
      </p>

      <h4>See also</h4>

      <p><a href="#color_floodfill">color_floodfill</a></p>

      <h4>Magick API</h4>

      <p>ColorFloodfillImage</p>
    </div>

    <div class="sig">
      <h3 id="color_floodfill">color_floodfill</h3>

      <p>
        <span class="arg">img</span>.color_floodfill(<span class="arg">x</span>, <span class="arg">y</span>, <span class="arg">fill_color</span>) -&gt;
        <em>image</em>
      </p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>Changes any pixel that is the same color and is a neighbor of the target pixel to the fill color.</p>

      <h4>Arguments</h4>

      <dl>
        <dt>x, y</dt>

        <dd>The target pixel's location.</dd>

        <dt>fill_color</dt>

        <dd>
          The fill color, either color name or a
          <a href="struct.html#Pixel">Pixel</a> object.
        </dd>
      </dl>

      <h4>Returns</h4>

      <p>A new image</p>

      <h4>Example</h4>

      <p>
        In this example, the aquamarine fill starts at the center of the circle and replaces all neighboring white pixels. Contrast the result of
        <code>color_floodfill</code> with that of <code>color_fill_to_border</code>, above.
      </p>

      <p class="rollover">
        <a href="javascript:popup('color_floodfill.rb.html')"
          ><img
            onmouseover="this.src='ex/color_floodfill_before.gif'"
            onmouseout="this.src='ex/color_floodfill_after.gif'"
            src="ex/color_floodfill_after.gif"
            alt="color_floodfill example"
            title="Click the image to see the example script"
        /></a>
        <img src="ex/images/spin.gif" alt="" class="spin" style="margin-bottom: 182px" title="Mouse over the example to see the original image" />
      </p>

      <h4>See also</h4>

      <p>
        <a href="#color_fill_to_border">color_fill_to_border</a>,
        <a href="image2.html#opaque">opaque</a>
      </p>

      <h4>Magick API</h4>

      <p>ColorFloodfillImage</p>
    </div>

    <div class="sig">
      <h3 id="color_histogram">color_histogram</h3>

      <p><span class="arg">img</span>.color_histogram() -&gt; <em>hash</em></p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>Computes the number of times each unique color appears in the image.</p>

      <h4>Returns</h4>

      <p>
        A hash. Each key in the hash is a
        <a href="struct.html#Pixel">pixel</a> representing a color that appears in the image. The value associated with the key is the number of times that
        color appears in the image. <em>Caution:</em> if the image contains many colors the hash will be very large. You may want to use the
        <a href="image3.html#quantize">quantize</a>
        method to reduce the number of colors before using
        <code>color_histogram</code>.
      </p>

      <h4>Example</h4>

      <p>
        This histogram was produced by sorting the hash returned by
        <code>color_histogram</code> by increasing frequency.
      </p>

      <p>
        <a href="javascript:popup('color_histogram.rb.html')"
          ><img src="ex/color_histogram.gif" alt="color_histogram example" title="Click the image to see the example script"
        /></a>
      </p>

      <h4>Magick API</h4>

      <p>GetImageHistogram</p>
    </div>

    <div class="sig">
      <h3 id="colorize">colorize</h3>

      <p>
        <span class="arg">img</span>.colorize(<span class="arg">red_pct</span>, <span class="arg">green_pct</span>, <span class="arg">blue_pct</span>, [<span
          class="arg"
          >matte_pct</span
        >, ] <span class="arg">fill</span>) -&gt; <em>image</em>
      </p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>
        Blend the fill color with the image pixels. The red_pct, green_pct, blue_pct and matte_pct arguments are the percentage to blend with the red, green,
        blue and matte channels.
      </p>

      <h4>Arguments</h4>

      <dl>
        <dt>red_pct, green_pct, blue_pct, matte_pct</dt>

        <dd>
          The percentage of the fill color red, green, blue and matte (transparency) components to blend with the image pixel. For example,
          <code>.25</code> is 25%. The matte_pct argument is optional.
        </dd>

        <dt>fill</dt>

        <dd>A color name or a <a href="struct.html#Pixel">Pixel</a></dd>
      </dl>

      <h4>Returns</h4>

      <p>A new image</p>

      <h4>Example</h4>

      <p>
        This example converts a color image to a "sepia-tone-ish" image using the <a href="image3.html#quantize">quantize</a> and <code>colorize</code> methods.
      </p>

      <p class="rollover">
        <a href="javascript:popup('colorize.rb.html')"
          ><img
            onmouseover="this.src='ex/images/Flower_Hat.jpg'"
            onmouseout="this.src='ex/colorize.jpg'"
            src="ex/colorize.jpg"
            alt="colorize example"
            title="Click the image to see the example script"
        /></a>
        <img src="ex/images/spin.gif" alt="" class="spin" title="Mouse over the example to see the original image" />
      </p>

      <h4>See also</h4>

      <p><a href="image3.html#sepiatone">sepiatone</a></p>

      <h4>Magick API</h4>

      <p>ColorizeImage</p>
    </div>

    <div class="sig">
      <h3 id="colormap">colormap</h3>

      <p><span class="arg">img</span>.colormap(<span class="arg">index</span>[, <span class="arg">new_color</span>]) -&gt; <em>string</em></p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>
        Returns the color in the color map at the specified index. If the
        <span class="arg">new_color</span> argument is specified, replaces the color at that index with the new color.
      </p>

      <p>
        Raises IndexError if the image does not contain a color map. Only
        <a href="constants.html#ClassType">PseudoClass</a> images have a color map.
      </p>

      <h4>Arguments</h4>

      <dl>
        <dt>index</dt>

        <dd>
          A number between 0 and the number of colors in the color map. If the value is out of range, <code>colormap</code> raises an IndexError. You can get
          the number of colors in the color map from the <a href="imageattrs.html#colors">colors</a> attribute.
        </dd>

        <dt>new_color</dt>

        <dd>
          Optional. If specified, may be either a
          <a href="imusage.html#color_names">color name</a> or a <a href="struct.html#Pixel">pixel</a>.
        </dd>
      </dl>

      <h4>Returns</h4>

      <p>The name of the color at the specified location in the color map</p>
    </div>

    <div class="sig">
      <h3 id="color_point">color_point</h3>

      <p>
        <span class="arg">img</span>.color_point(<span class="arg">x</span>, <span class="arg">y</span>, <span class="arg">fill</span>) -&gt;
        <em>image</em>
      </p>
    </div>

    <div class="desc">
      <h4>Description</h4>
      Set the color of the pixel at <span class="arg">x</span>,<span class="arg">y</span>
      to the fill color. This method creates a new image object. If you want to set a single pixel in the image without creating a new image, use
      <a href="image3.html#pixel_color">pixel_color</a> or the <a href="draw.html#point">Draw#point</a> method.

      <h4>Arguments</h4>

      <dl>
        <dt>x, y</dt>

        <dd>The location of the pixel.</dd>

        <dt>fill</dt>

        <dd>
          The fill color, either color name or a
          <a href="struct.html#Pixel">Pixel</a> object.
        </dd>
      </dl>

      <h4>Returns</h4>

      <p>A new image</p>

      <h4>Example</h4>
      <pre>
f.color_point(50,50, 'red')
</pre
      >

      <h4>See also</h4>

      <p>
        <a href="image3.html#pixel_color">pixel_color</a>,
        <a href="draw.html#point">Draw#point</a>
      </p>

      <h4>Magick API</h4>

      <p>GetImagePixels, SyncImagePixels</p>
    </div>

    <div class="sig">
      <h3 id="color_reset_bang">color_reset!</h3>

      <p><span class="arg">img</span>.color_reset!(<span class="arg">fill</span>) -&gt; <em>self</em></p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>Sets all the pixels in the image to the specified fill color.</p>

      <h4>Arguments</h4>
      The fill color, either color name or a
      <a href="struct.html#Pixel">Pixel</a> object.

      <h4>Returns</h4>
      self

      <h4>Example</h4>
      <pre>
f.color_reset!(red)
</pre
      >

      <h4>See also</h4>

      <p><a href="image2.html#erase_bang">erase!</a></p>

      <h4>Magick API</h4>
      SetImage
    </div>

    <div class="sig">
      <h3 id="compare_channel">compare_channel</h3>

      <p>
        <span class="arg">img</span>.compare_channel(<span class="arg">img</span>, <span class="arg">metric</span> [, <span class="arg">channel...</span>]) [
        <span class="arg">{&nbsp;optional arguments&nbsp;}</span> ] -&gt; [<em>image</em>, <em>float</em>]
      </p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>Compares <span class="arg">img</span> with the receiver.</p>

      <h4>Arguments</h4>

      <dl>
        <dt>image</dt>

        <dd>Either an imagelist or an image. If an imagelist, uses the current image.</dd>

        <dt>metric</dt>

        <dd>
          The desired distortion metric. A
          <a href="constants.html#MetricType">MetricType</a> value.
        </dd>

        <dt>channel...</dt>

        <dd>
          Zero or more
          <a href="constants.html#ChannelType">ChannelType</a> values. All the specified channels contribute to the comparison and the distortion value. If no
          channels are specified, compares all channels.
        </dd>

        <dt>optional arguments</dt>

        <dd>
          If present, <code>compare_channel</code> yields to a block in which you can set optional arguments by setting attributes on <em>self</em>. In both
          cases <span class="arg">color</span> may be either a <a href="imusage.html#color_names">color name</a> or a <a href="struct.html#Pixel">pixel</a>.

          <dl>
            <dt>options.highlight_color = color</dt>

            <dd>Emphasize pixel differences with this color. The default is partially transparent red.</dd>

            <dt>options.lowlight_color = color</dt>

            <dd>Demphasize pixel differences with this color. The default is partially transparent white.</dd>
          </dl>
        </dd>
      </dl>

      <h4>Returns</h4>

      <p>An array. The first element is a difference image, the second is a the value of the computed distortion represented as a <code>Float</code>.</p>

      <h4>See also</h4>

      <p>
        <a href="#difference">difference</a>, <a href="#spaceship">&lt;=&gt;</a>,
        <a href="#distortion_channel">distortion_channel</a>
      </p>

      <h4>Magick API</h4>

      <p>ImageCompareChannels</p>

      <h4>Notes</h4>

      <p>This method was named <code>channel_compare</code> in earlier releases of RMagick. That name remains an alias for <code>compare_channel</code>.</p>
    </div>

    <div class="sig">
      <h3 id="composite">composite</h3>

      <p>
        <span class="arg">dest</span>.composite(<span class="arg">src</span>, <span class="arg">x</span>, <span class="arg">y</span>,
        <span class="arg">composite_op</span>) -&gt; <em>image</em><br />
        <span class="arg">dest</span>.composite(<span class="arg">src</span>, <span class="arg">gravity</span>, <span class="arg">composite_op</span>) -&gt;
        <em>image</em><br />
        <span class="arg">dest</span>.composite(<span class="arg">src</span>, <span class="arg">gravity</span>, <span class="arg">x</span>,
        <span class="arg">y</span>, <span class="arg">composite_op</span>) -&gt;
        <em>image</em>
      </p>
    </div>

    <div class="desc">
      <h4>Description</h4>
      Composites <span class="arg">src</span> onto <span class="arg">dest</span> using the specified composite operator.

      <h4>Arguments</h4>

      <p>The composite method can be called three different ways:</p>

      <dl>
        <dt style="font-style: normal">1.&nbsp;Without a gravity argument:</dt>

        <dd>
          <dl>
            <dt>src</dt>

            <dd>Either an imagelist or an image. If an imagelist, uses the current image.</dd>

            <dt>x, y</dt>

            <dd>The x- and y-offset of the composited image, measured from the upper-left corner of the image.</dd>

            <dt>composite_op</dt>

            <dd>
              A
              <a href="constants.html#CompositeOperator">CompositeOperator</a>
              value.
            </dd>
          </dl>
        </dd>

        <dt style="font-style: normal">2.&nbsp;With a gravity argument, without x and y arguments:</dt>

        <dd>
          <dl>
            <dt>src</dt>

            <dd>Either an imagelist or an image. If an imagelist, uses the current image.</dd>

            <dt>gravity</dt>

            <dd>
              A <a href="constants.html#GravityType">GravityType</a> value that specifies the location of <em>img</em> on <em>image</em>:

              <dl>
                <dt>NorthWestGravity</dt>

                <dd>The composited image abuts the top and left sides of the image.</dd>

                <dt>NorthGravity</dt>

                <dd>The composited image is centered left-to-right and abuts the top of the image.</dd>

                <dt>NorthEastGravity</dt>

                <dd>The composited image abuts the top and right sides of the image.</dd>

                <dt>EastGravity</dt>

                <dd>The composited image is centered top-to-bottom and abuts the right side of the image.</dd>

                <dt>SouthEastGravity</dt>

                <dd>The composited image abuts the bottom and right sides of the image.</dd>

                <dt>SouthGravity</dt>

                <dd>The composited image is centered left-to-right and abuts the bottom of the image.</dd>

                <dt>SouthWestGravity</dt>

                <dd>The composited image abuts the bottom and left sides of the image.</dd>

                <dt>WestGravity</dt>

                <dd>The composited image is centered top-to-bottom and abuts the left side of the image.</dd>

                <dt>CenterGravity</dt>

                <dd>The composited image is centered left-to-right and top-to-bottom.</dd>
              </dl>
            </dd>

            <dt>composite_op</dt>

            <dd>
              A
              <a href="constants.html#CompositeOperator">CompositeOperator</a>
              value.
            </dd>
          </dl>
        </dd>

        <dt style="font-style: normal">3.&nbsp;With gravity, x, and y arguments:</dt>

        <dd>
          <dl>
            <dt>src</dt>

            <dd>Either an imagelist or an image. If an imagelist, uses the current image.</dd>

            <dt>gravity</dt>

            <dd>A <a href="constants.html#GravityType">GravityType</a> value.</dd>

            <dt>x, y</dt>

            <dd>The x- and y-offset of the composited image, measured relative to the <em>gravity</em> argument.</dd>

            <dt>composite_op</dt>

            <dd>
              A
              <a href="constants.html#CompositeOperator">CompositeOperator</a>
              value.
            </dd>
          </dl>
        </dd>
      </dl>

      <h4>Returns</h4>

      <p>A new image</p>

      <h4>Example</h4>

      <p>This example shows the effect of some of the composite operators.</p>

      <p>
        <a href="javascript:popup('composite.rb.html')"
          ><img src="ex/composite.gif" alt="composite example" title="Click the image to see the example script"
        /></a>
      </p>

      <h4>See also</h4>

      <p>
        <a href="#composite_bang">composite!</a>, <a href="#dissolve">dissolve</a>,
        <a href="image3.html#watermark">watermark</a>
      </p>

      <h4>Magick API</h4>

      <p>CompositeImage</p>
    </div>

    <div class="sig">
      <h3 id="composite_bang">composite!</h3>

      <p>
        <span class="arg">dest</span>.composite!(<span class="arg">src</span>, <span class="arg">x</span>, <span class="arg">y</span>,
        <span class="arg">composite_op</span>) -&gt; <em>self</em><br />
        <span class="arg">dest</span>.composite!(<span class="arg">src</span>, <span class="arg">gravity</span>, <span class="arg">composite_op</span>) -&gt;
        <em>self</em><br />
        <span class="arg">dest</span>.composite!(<span class="arg">src</span>, <span class="arg">gravity</span>, <span class="arg">x</span>,
        <span class="arg">y</span>, <span class="arg">composite_op</span>) -&gt;
        <em>self</em>
      </p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>In-place form of <a href="#composite">composite</a>.</p>

      <h4>Returns</h4>

      <p>self</p>
    </div>

    <div class="sig">
      <h3 id="composite_affine">composite_affine</h3>

      <p><span class="arg">dest</span>.composite_affine(<span class="arg">src</span>, <span class="arg">affine</span>) -&gt; <em>image</em></p>
    </div>

    <div class="desc">
      <h4>Description</h4>
      Composite <span class="arg">src</span> over <span class="arg">dest</span> as dictated by the <span class="arg">affine</span> argument.

      <h4>Arguments</h4>

      <dl>
        <dt>img</dt>

        <dd>An image or imagelist</dd>

        <dt>affine</dt>

        <dd>An <code>AffineMatrix</code></dd>
      </dl>

      <h4>Returns</h4>

      <p>A new image</p>

      <h4>See also</h4>

      <p>
        <a href="#composite">composite</a>,
        <a href="#affine_transform">affine_transform</a>
      </p>

      <h4>Magick API</h4>

      <p>DrawAffineImage</p>
    </div>

    <div class="sig">
      <h3 id="composite_mathematics">composite_mathematics</h3>

      <p>
        <span class="arg">dest</span>.composite_mathematics(<span class="arg">src</span>, <span class="arg">a</span>, <span class="arg">b</span>,
        <span class="arg">c</span>, <span class="arg">d</span>, <span class="arg">gravity</span>) -&gt; <em>image</em><br />
        <span class="arg">dest</span>.composite_mathematics(<span class="arg">src</span>, <span class="arg">a</span>, <span class="arg">b</span>,
        <span class="arg">c</span>, <span class="arg">d</span>, <span class="arg">x</span>, <span class="arg">y</span>) -&gt; <em>image</em><br />
        <span class="arg">dest</span>.composite_mathematics(<span class="arg">src</span>, <span class="arg">a</span>, <span class="arg">b</span>,
        <span class="arg">c</span>, <span class="arg">d</span>, <span class="arg">gravity</span>, <span class="arg">x</span>, <span class="arg">y</span>) -&gt;
        <em>image</em>
      </p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>
        Merge the source and destination images according to the formula
        <em>a*Sc*Dc&nbsp;+&nbsp;b*Sc&nbsp;+&nbsp;c*Dc&nbsp;+&nbsp;d</em>
        where Sc is the source pixel and Dc is the destination pixel.
      </p>

      <p>
        Equivalent to the
        <code>-compose Mathematics -set option:compose:args a,b,c,d</code>
        options to ImagMagick's <code>convert</code> command. See
        <a href="https://www.imagemagick.org/Usage/compose/#mathematics">Examples of ImageMagick Usage</a>.
      </p>

      <h4>Arguments</h4>

      <dl>
        <dt>src</dt>

        <dd>Either an imagelist or an image. If an imagelist, uses the current image.</dd>

        <dt>a, b, c, d</dt>

        <dd>See the description.</dd>

        <dt>gravity</dt>

        <dd>A <a href="constants.html#GravityType">GravityType</a> value. If omitted, the default gravity is NorthWestGravity.</dd>

        <dt>x, y</dt>

        <dd>
          The x- and y-offset of the composited image, measured relative to the
          <em>gravity</em> argument. If omitted, the default value is 0.0.
        </dd>
      </dl>

      <h4>Returns</h4>

      <p>A new image</p>

      <h4>See also</h4>

      <p><a href="#composite">composite</a></p>

      <h4>Magick API</h4>

      <p>CompositeImage</p>
    </div>

    <div class="sig">
      <h3 id="composite_tiled">composite_tiled</h3>

      <p>
        <span class="arg">img</span>.composite_tiled(<span class="arg">src</span>, <span class="arg">composite_op</span> = Magick::OverCompositeOp) -&gt;
        <em>image</em>
      </p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>
        Composites multiple copies of the source image across and down the image, producing the same results as ImageMagick's composite command with the -tile
        option.
      </p>

      <h4>Arguments</h4>

      <dl>
        <dt>src</dt>

        <dd>The source image</dd>

        <dt>composite_op</dt>

        <dd>
          A
          <a href="constants.html#CompositeOperator">CompositeOperator</a> value
        </dd>
      </dl>

      <h4>Returns</h4>

      <p>A new image</p>

      <h4>See also</h4>

      <p>
        <a href="#composite">composite</a>,
        <a href="#composite_tiled_bang">composite_tiled!</a>
      </p>

      <h4>Magick API</h4>

      <p>CompositeImage</p>
    </div>

    <div class="sig">
      <h3 id="composite_tiled_bang">composite_tiled!</h3>

      <p>
        <span class="arg">img</span>.composite_tiled!(<span class="arg">src</span>, <span class="arg">composite_op</span> = Magick::OverCompositeOp) -&gt;
        <em>self</em>
      </p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>In-place form of <a href="#composite_tiled">composite_tiled</a>.</p>

      <h4>Example</h4>

      <p class="rollover">
        <a href="javascript:popup('composite_tiled.rb.html')"
          ><img
            onmouseover="this.src='ex/images/Flower_Hat.jpg'"
            onmouseout="this.src='ex/composite_tiled.jpg'"
            src="ex/composite_tiled.jpg"
            alt="composite_tiled example"
            title="Click the image to see the example script"
        /></a>
        <img src="ex/images/spin.gif" alt="" class="spin" title="Mouse over the example to see the original image" />
      </p>

      <h4>Returns</h4>

      <p>self</p>

      <h4>See also</h4>

      <p>
        <a href="#composite_bang">composite!</a>,
        <a href="#composite_tiled">composite_tiled</a>
      </p>

      <h4>Magick API</h4>

      <p>CompositeImage</p>
    </div>

    <div class="sig">
      <h3 id="compress_colormap">compress_colormap</h3>

      <p><span class="arg">img</span>.compress_colormap! -&gt; <em>self</em></p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>
        Removes duplicate or unused entries in the colormap. Only
        <a href="constants.html#ClassType">PseudoClass</a> images have a colormap. If the image is <code>DirectClass</code> then
        <code>compress_colormap!</code> converts it to <code>PseudoClass</code>.
      </p>

      <h4>Returns</h4>
      self

      <h4>Example</h4>
      <pre>
f = Image.read('cbezier1.gif').first &raquo;
 cbezier1.gif GIF 500x350+0+0 PseudoClass 128c 8-bit 177503b
f.colors &raquo; 128
f.compress_colormap! &raquo;
 cbezier1.gif GIF 500x350+0+0 PseudoClass 108c 8-bit 177503b
f.colors &raquo; 108
</pre
      >

      <h4>Magick API</h4>

      <p>CompressColormap</p>
    </div>

    <div class="sig">
      <h3 id="contrast">contrast</h3>

      <p><span class="arg">img</span>.contrast(<span class="arg">sharpen</span>=<code>false</code>) -&gt; <em>image</em></p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p class="imquote">Enhances or reduces the intensity differences between the lighter and darker elements of the image.</p>

      <h4>Arguments</h4>
      If <span class="arg">sharpen</span> is <code>true</code>, the contrast is increased, otherwise it is reduced.

      <h4>Returns</h4>

      <p>A new image</p>

      <h4>Example</h4>

      <p>In this example the contrast is <em>reduced</em> in each successive image.</p>
      <a href="javascript:popup('contrast.rb.html')"><img src="ex/contrast.jpg" alt="contrast example" title="Click the image to see the example script" /></a>

      <h4>See also</h4>

      <p>
        <a href="#contrast_stretch_channel">contrast_stretch_channel</a>,
        <a href="image3.html#sigmoidal_contrast_channel">sigmoidal_contrast_channel</a>
      </p>

      <h4>Magick API</h4>

      <p>ContrastImage</p>
    </div>

    <div class="sig">
      <h3 id="contrast_stretch_channel">contrast_stretch_channel</h3>

      <p>
        <span class="arg">img</span>.contrast_stretch_channel(<span class="arg">black_point</span> [, <span class="arg">white_point</span>] [,
        <span class="arg">channel</span>...]) -&gt;
        <span class="arg">image</span>
      </p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>
        This method
        <span class="imquote"
          >is a simple image enhancement technique that attempts to improve the contrast in an image by `stretching' the range of intensity values it contains
          to span a desired range of values. It differs from the more sophisticated histogram equalization in that it can only apply a linear scaling function
          to the image pixel values. As a result the `enhancement' is less harsh.</span
        >
      </p>

      <h4>Arguments</h4>

      <dl>
        <dt>black_point</dt>

        <dd>black out at most this many pixels. Specify an absolute number of pixels as a numeric value, or a percentage as a string in the form 'NN%'.</dd>

        <dt>white_point</dt>

        <dd>
          burn at most this many pixels. Specify an absolute number of pixels as a numeric value, or a percentage as a string in the form 'NN%'. This argument
          is optional. If not specified the default is
          <code>all pixels - black_point pixels</code>.
        </dd>

        <dt>channel...</dt>

        <dd>
          0 or more
          <a href="constants.html#ChannelType">ChannelType</a> arguments. If no channels are specified all channels are included.
        </dd>
      </dl>

      <h4>Returns</h4>

      <p>A new image</p>

      <h4>See also</h4>

      <p>
        <a href="#contrast">contrast</a>,
        <a href="image2.html#equalize">equalize</a>
      </p>

      <h4>Magick API</h4>

      <p>ContrastStretchImage</p>
    </div>

    <div class="sig">
      <h3 id="convolve">convolve</h3>

      <p><span class="arg">img</span>.convolve(<span class="arg">order</span>, <span class="arg">kernel</span>) -&gt; <em>image</em></p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p class="imquote">Applies a custom convolution kernel to the image.</p>

      <h4>Arguments</h4>

      <dl>
        <dt>order</dt>

        <dd>The number of columns and rows in the kernel.</dd>

        <dt>kernel</dt>

        <dd>An <span class="arg">order</span>*<span class="arg">order</span> matrix of <code>Float</code> values.</dd>
      </dl>

      <h4>Returns</h4>

      <p>A new image</p>

      <h4>See also</h4>

      <p>
        <a href="#convolve_channel">convolve_channel</a>. The <a href="image2.html#edge">edge</a>, <a href="image2.html#emboss">emboss</a>,
        <a href="image2.html#gaussian_blur">gaussian_blur</a>, <a href="image2.html#motion_blur">motion_blur</a> and
        <a href="image2.html#sharpen">sharpen</a> methods use convolution to do their work.
      </p>

      <h4>Magick API</h4>

      <p>ConvolveImage</p>

      <h4>Note</h4>

      <p>
        See
        <a href="https://www.dai.ed.ac.uk/HIPR2/convolve.htm">Convolution</a> in the
        <a href="https://www.dai.ed.ac.uk/HIPR2/copyrght.htm"><cite>Hypermedia Image Processing Reference</cite></a>
      </p>
    </div>

    <div class="sig">
      <h3 id="convolve_channel">convolve_channel</h3>

      <p>
        <span class="arg">img</span>.convolve_channel(<span class="arg">order</span>, <span class="arg">kernel</span> [, <span class="arg">channel</span>...])
        -&gt; <em>image</em>
      </p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>Applies a custom convolution kernel to the specified channel or channels in the image.</p>

      <h4>Arguments</h4>

      <dl>
        <dt>order</dt>

        <dd>The number of columns and rows in the kernel.</dd>

        <dt>kernel</dt>

        <dd>An <span class="arg">order</span>*<span class="arg">order</span> matrix of <code>Float</code> values.</dd>

        <dt>channel...</dt>

        <dd>
          0 or more
          <a href="constants.html#ChannelType">ChannelType</a> arguments. If no channels are specified the effect is the same as calling
          <a href="#convolve">convolve</a>.
        </dd>
      </dl>

      <h4>Returns</h4>

      <p>A new image</p>

      <h4>Magick API</h4>

      <p>ConvolveImageChannel</p>

      <h4>See also</h4>

      <p><a href="#convolve">convolve</a></p>
    </div>

    <div class="sig">
      <h3 id="copy">copy</h3>

      <p><span class="arg">img</span>.copy -&gt; <em>other_image</em></p>
    </div>

    <div class="desc">
      <h4>Description</h4>
      Returns a copy of the image. The tainted state of the original is propagated to the copy.

      <h4>Example</h4>
      <pre>
f2 = f.copy
</pre
      >

      <h4>See also</h4>

      <p>
        <a href="#clone">clone</a>, <a href="#dup">dup</a>,
        <a href="ilist.html#copy">ImageList#copy</a>
      </p>

      <h4>Magick API</h4>

      <p>CloneImage</p>
    </div>

    <div class="sig">
      <h3 id="crop">crop</h3>

      <p>
        <span class="arg">img</span>.crop(<span class="arg">x</span>, <span class="arg">y</span>, <span class="arg">width</span>,
        <span class="arg">height</span>) -&gt; <em>image</em><br />
        <span class="arg">img</span>.crop(<span class="arg">gravity</span>, <span class="arg">x</span>, <span class="arg">y</span>,
        <span class="arg">width</span>, <span class="arg">height</span>) -&gt; <em>image</em><br />
        <span class="arg">img</span>.crop(<span class="arg">gravity</span>, <span class="arg">width</span>, <span class="arg">height</span>) -&gt;
        <em>image</em>
      </p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>Extracts the specified rectangle from the image.</p>

      <h4>Arguments</h4>

      <p>The crop method can be called three different ways:</p>

      <dl>
        <dt style="font-style: normal">1.&nbsp;Without a <em>gravity</em> argument:</dt>

        <dd>
          <dl>
            <dt>x, y</dt>

            <dd>The <em>x-</em> and <em>y-</em>offset of the rectangle relative to the upper-left corner of the image</dd>

            <dt>width, height</dt>

            <dd>The width and height of the rectangle.</dd>
          </dl>
        </dd>

        <dt style="font-style: normal">2.&nbsp;With a <em>gravity</em> argument, but without <em>x</em> and <em>y</em> arguments:</dt>

        <dd>
          <dl>
            <dt>gravity</dt>

            <dd>
              A <a href="constants.html#GravityType">GravityType</a>
              value specifying the position of the rectangle.

              <dl>
                <dt>NorthWestGravity</dt>

                <dd>The rectangle abuts the top and left sides of the image.</dd>

                <dt>NorthGravity</dt>

                <dd>The rectangle is centered left-to-right and abuts the top of the image.</dd>

                <dt>NorthEastGravity</dt>

                <dd>The rectangle abuts the top and right sides of the image.</dd>

                <dt>EastGravity</dt>

                <dd>The rectangle is centered top-to-bottom and abuts the right side of the image.</dd>

                <dt>SouthEastGravity</dt>

                <dd>The rectangle abuts the bottom and right sides of the image.</dd>

                <dt>SouthGravity</dt>

                <dd>The rectangle is centered left-to-right and abuts the bottom of the image.</dd>

                <dt>SouthWestGravity</dt>

                <dd>The rectangle abuts the bottom and left sides of the image.</dd>

                <dt>WestGravity</dt>

                <dd>The rectangle is centered top-to-bottom and abuts the left side of the image.</dd>

                <dt>CenterGravity</dt>

                <dd>The rectangle is centered left-to-right and top-to-bottom.</dd>
              </dl>
            </dd>

            <dt>width, height</dt>

            <dd>The width and height of the rectangle.</dd>
          </dl>
        </dd>

        <dt style="font-style: normal">3.&nbsp;With <em>gravity</em>, <em>x</em>, and <em>y</em> arguments:</dt>

        <dd>
          <dl>
            <dt>gravity</dt>

            <dd>
              A <a href="constants.html#GravityType">GravityType</a> value. If the argument is NorthEastGravity, EastGravity, or SouthEastGravity, the
              <em>x-</em>offset is measured from the right side of the image. If the argument is SouthEastGravity, SouthGravity, or SouthWestGravity, the
              <em>y-</em>offset is measured from the bottom of the image. All other values are ignored and the <em>x-</em> and <em>y-</em>offsets are measured
              from the upper-left corner of the image.
            </dd>

            <dt>x, y</dt>

            <dd>The <em>x-</em> and <em>y-</em>offset of the rectangle from the sides specified by the <em>gravity</em> argument.</dd>

            <dt>width, height</dt>

            <dd>The width and height of the rectangle.</dd>
          </dl>
        </dd>
      </dl>

      <h4>Notes</h4>
      The <code>crop</code> method retains the offset information in the cropped image. This may cause the image to appear to be surrounded by blank or black
      space when viewed with an external viewer. This only occurs when the image is saved in a format (such as GIF) that saves offset information. To reset the
      offset data, add <code>true</code> as the last argument to <code>crop</code>. For example,
      <pre>
cropped = img.crop(x, y, width, height, true)
</pre
      >

      <p>You can add <code>true</code> as the last argument with any of the three argument list formats described above.</p>

      <h4>Returns</h4>

      <p>A new image</p>

      <h4>Example</h4>

      <p>The crop rectangle is highlighted in the "before" image.</p>

      <p class="rollover">
        <a href="javascript:popup('crop.rb.html')"
          ><img
            onmouseover="this.src='ex/crop_before.png'"
            onmouseout="this.src='ex/crop_after.png'"
            src="ex/crop_after.png"
            alt="crop example"
            title="Click the image to see the example script" /></a
        ><img src="ex/images/spin.gif" alt="" class="spin" title="Mouse over the example to see the original image" />
      </p>

      <h4>Example 2</h4>

      <p>
        <a href="javascript:popup('crop_with_gravity.rb.html')">crop_with_gravity.rb</a>
      </p>

      <h4>See also</h4>

      <p>
        <a href="#crop_bang">crop!</a>, <a href="#chop">chop</a>,
        <a href="image2.html#excerpt">excerpt</a>
      </p>

      <h4>Magick API</h4>

      <p>CropImage</p>
    </div>

    <div class="sig">
      <h3 id="crop_bang">crop!</h3>

      <p>
        <span class="arg">img</span>.crop!(<span class="arg">x</span>, <span class="arg">y</span>, <span class="arg">width</span>,
        <span class="arg">height</span>) -&gt; <em>self</em><br />
        <span class="arg">img</span>.crop!(<span class="arg">gravity</span>, <span class="arg">x</span>, <span class="arg">y</span>,
        <span class="arg">width</span>, <span class="arg">height</span>) -&gt; <em>self</em><br />
        <span class="arg">img</span>.crop!(<span class="arg">gravity</span>, <span class="arg">width</span>, <span class="arg">height</span>) -&gt;
        <em>self</em>
      </p>
    </div>

    <div class="desc">
      <h4>Description</h4>
      The in-place form of <a href="#crop">crop</a>.

      <h4>Returns</h4>

      <p>self</p>
    </div>

    <div class="sig">
      <h3 id="crop_resized">crop_resized</h3>

      <p>
        <span class="arg">img</span>.crop_resized(<span class="arg">width</span>, <span class="arg">height</span>, gravity=CenterGravity) -&gt;
        <em>image</em>
      </p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>An alias for <a href="image3.html#resize_to_fill">resize_to_fill</a>.</p>
    </div>

    <div class="sig">
      <h3 id="cycle_colormap">cycle_colormap</h3>

      <p><span class="arg">img</span>.cycle_colormap(<span class="arg">amount</span>) -&gt; <em>image</em></p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p class="imquote">
        Displaces the colormap by a given number of positions. If you cycle the colormap a number of times you can produce a psychedelic effect.
      </p>

      <p>The returned image is always a <code>PseudoClass</code> image, regardless of the type of the original image.</p>

      <h4>Arguments</h4>

      <p>The number of positions to cycle.</p>

      <h4>Returns</h4>

      <p>A new image</p>

      <h4>Example</h4>

      <p>Mouse over the image to see an animation made by cycling the colormap between each copy.</p>

      <p class="rollover">
        <a href="javascript:popup('cycle_colormap.rb.html')"
          ><img
            onmouseover="this.src='ex/cycle_colormap.gif'"
            onmouseout="this.src='ex/images/Hot_Air_Balloons.jpg'"
            src="ex/images/Hot_Air_Balloons.jpg"
            alt="cycle_colormap example"
            title="Click the image to see the example script" /></a
        ><img src="ex/images/spin.gif" alt="" class="spin" style="left: 191px" title="Mouse over the example to see the animation" />
      </p>

      <h4>Magick API</h4>

      <p>CycleColormapImage</p>
    </div>

    <div class="sig">
      <h3 id="decipher">decipher</h3>

      <p><span class="arg">img</span>.decipher(<span class="arg">passphrase</span>) -&gt; <em>image</em></p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>Decipher an enciphered image.</p>

      <h4>Arguments</h4>

      <p>The passphrase used to encipher the image.</p>

      <h4>Returns</h4>

      <p>A new image</p>

      <h4>Example</h4>
      <pre>
deciphered_img = img.decipher("magic word")
</pre
      >

      <h4>Magick API</h4>

      <p>DecipherImage</p>

      <h4>See also</h4>

      <p><a href="image2.html#encipher">encipher</a></p>
    </div>

    <div class="sig">
      <h3 id="delete_compose_mask">delete_compose_mask</h3>

      <p><span class="arg">img</span>.delete_compose_mask() -&gt; <em>self</em></p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>
        Deletes the mask added by
        <a href="#add_compose_mask">add_compose_mask</a>.
      </p>

      <h4>Returns</h4>

      <p>self</p>

      <h4>See also</h4>

      <p><a href="#add_compose_mask">add_compose_mask</a></p>

      <h4>Magick API</h4>

      <p>SetImageMask</p>
    </div>

    <div class="sig">
      <h3 id="delete_profile">delete_profile</h3>

      <p><span class="arg">img</span>.delete_profile(<span class="arg">profile_name</span>) -&gt; <span class="arg">self</span></p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>
        Deletes the specified profile. This method is effectively the same as passing a <code>nil</code> 2nd argument to
        <a href="image3.html#profile_bang">profile!</a>.
      </p>

      <h4>Arguments</h4>

      <p>The profile name, "IPTC" or "ICC" for example. Specify "*" to delete all the profiles in the image.</p>

      <h4>See also</h4>

      <p>
        Setting the
        <a href="imageattrs.html#iptc_profile">iptc_profile</a> attribute or
        <a href="imageattrs.html#color_profile">color_profile</a>
        attribute to nil causes the profile to be deleted. Also see
        <a href="image3.html#strip_bang">strip!</a> and <a href="imageattrs.html#add_profile">add_profile</a>.
      </p>

      <h4>Magick API</h4>

      <p>ProfileImage</p>
    </div>

    <div class="sig">
      <h3 id="deskew">deskew</h3>

      <p>
        <span class="arg">img</span>.deskew(<span class="arg">threshold</span>=0.40, <span class="arg">auto_crop_width</span>=nil) -&gt;
        <em>image</em>
      </p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p class="imquote">Straightens an image. A <span class="arg">threshold</span> of 40% works for most images.</p>

      <h4>Arguments</h4>

      <dl>
        <dt>threshold</dt>

        <dd>A percentage of QuantumRange. Either a Float between 0 and 1.0, inclusive, or a string in the form "NN%" where NN is between 0 and 100.</dd>

        <dt>auto_crop_width</dt>

        <dd>
          Specify a value for this argument to cause the deskewed image to be auto-cropped. The argument is the pixel width of the image background (e.g. 40).
        </dd>
      </dl>

      <h4>Returns</h4>

      <p>A new image</p>

      <h4>Example</h4>
      <pre>
img2 = img.deskew
</pre
      >

      <h4>Magick API</h4>
      DeskewImage (available in 6.4.2)
    </div>

    <div class="sig">
      <h3 id="despeckle">despeckle</h3>

      <p><span class="arg">img</span>.despeckle -&gt; <em>image</em></p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p class="imquote">Reduces the speckle noise while preserving the edges.</p>

      <h4>Returns</h4>

      <p>A new image</p>

      <h4>Magick API</h4>

      <p>DespeckleImage</p>
    </div>

    <div class="sig">
      <h3 id="destroy_bang">destroy!</h3>

      <p><span class="arg">img</span>.destroy! -&gt; <em>self</em></p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>
        Returns all the memory associated with the image to the system. After an image has been destroyed, all Image methods (except
        <a href="image1.html#destroyed_q">destroyed?</a> and <a href="image2.html#inspect">inspect</a>) called on the image will raise a DestroyedImageError.
      </p>

      <p>It is not possible to recover a destroyed image.</p>

      <h4>Returns</h4>

      <p>self</p>

      <h4>See also</h4>

      <p>
        <a href="#check_destroyed">check_destroyed</a>,
        <a href="#destroyed_q">destroyed?</a>
      </p>
    </div>

    <div class="sig">
      <h3 id="destroyed_q">destroyed?</h3>

      <p>
        <span class="arg">img</span>.destroyed? -&gt; <code>true</code> or
        <code>false</code>
      </p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>Returns true if the image has been destroyed, false otherwise.</p>

      <h4>See also</h4>

      <p>
        <a href="#check_destroyed">check_destroyed</a>,
        <a href="#destroy_bang">destroy!</a>
      </p>
    </div>

    <div class="sig">
      <h3 id="difference">difference</h3>

      <p><span class="arg">img</span>.difference(<span class="arg">other</span>) -&gt; <em>array</em></p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p class="imquote">Compares two images and computes statistics about their difference.</p>

      <p class="imquote">A small normalized mean square error...suggests the images are very similar in spatial layout and color.</p>

      <h4>Returns</h4>

      <p>An array of three <code>Float</code> values:</p>

      <dl class="imquote">
        <dt>mean error per pixel</dt>

        <dd>The mean error for any single pixel in the image.</dd>

        <dt>normalized mean error</dt>

        <dd>
          The normalized mean quantization error for any single pixel in the image. This distance measure is normalized to a range between 0 and 1. It is
          independent of the range of red, green, and blue values in the image.
        </dd>

        <dt>normalized maximum error</dt>

        <dd>
          The normalized maximum quantization error for any single pixel in the image. This distance measure is normalized to a range between 0 and 1. It is
          independent of the range of red, green, and blue values in your image.
        </dd>
      </dl>

      <p>
        After <code>difference</code> returns, these values are also available from the <a href="imageattrs.html#mean_error_per_pixel">mean_error_per_pixel</a>,
        <a href="imageattrs.html#normalized_mean_error">normalized_mean_error</a>, and
        <a href="imageattrs.html#normalized_maximum_error">normalized_maximum_error</a>
        attributes.
      </p>

      <h4>See also</h4>

      <p><a href="#spaceship">&lt;=&gt;</a></p>

      <h4>Magick API</h4>
      IsImagesEqual
    </div>

    <div class="sig">
      <h3 id="dispatch">dispatch</h3>

      <p>
        <span class="arg">img</span>.dispatch(<span class="arg">x</span>, <span class="arg">y</span>, <span class="arg">columns</span>,
        <span class="arg">rows</span>, <span class="arg">map</span>, <span class="arg">float</span>=<code>false</code>) -&gt; <em>array</em>
      </p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>Extracts the pixel data from the specified rectangle and returns it as an array of either <code>Integer</code> or <code>Float</code> values.</p>

      <p>The array returned by <code>dispatch</code> is suitable for use as an argument to <code>constitute</code>.</p>

      <h4>Arguments</h4>

      <dl>
        <dt>x, y</dt>

        <dd>The offset of the rectangle from the upper-left corner of the image.</dd>

        <dt>columns, rows</dt>

        <dd>The width and height of the rectangle.</dd>

        <dt>map</dt>

        <dd>
          A <code>String</code> reflecting the order of the pixel data.
          <span class="imquote"
            >It can be any combination or order of R = red, G = green, B = blue, A = alpha, C = cyan, Y = yellow, M = magenta, K = black, or I = intensity (for
            grayscale).</span
          >
        </dd>

        <dt>float</dt>

        <dd>
          If <code>true</code>, the returned array elements will be <code>Float</code> values in the range 0..1. If <code>false</code>, the returned array
          elements will be <code>Integer</code> values in the range 0..QuantumRange.
        </dd>
      </dl>

      <h4>Returns</h4>
      An array

      <h4>Example</h4>
      <pre>
pixels = f.dispatch(0, 0, f.columns, f.rows, "RGB")
</pre
      >

      <h4>See also</h4>

      <p>
        <a href="#constitute">constitute</a>, <a href="image2.html#export_pixels">export_pixels</a>,
        <a href="image2.html#get_pixels">get_pixels</a>
      </p>

      <h4>Magick API</h4>

      <p>ExportImagePixels</p>

      <h4>Note</h4>

      <p>
        This method is deprecated in ImageMagick. Use the
        <code>export_pixels</code> method instead.
      </p>
    </div>

    <div class="sig">
      <h3 id="displace">displace</h3>

      <p>
        <span class="arg">img</span>.displace(<span class="arg">displacement_map</span>, <span class="arg">x_amplitude</span>,
        <span class="arg">y_amplitude</span>, <span class="arg">x_offset</span>=0, <span class="arg">y_offset</span>=0) -&gt; <em>image</em><br />
        <span class="arg">img</span>.displace(<span class="arg">displacement_map</span>, <span class="arg">x_amplitude</span>,
        <span class="arg">y_amplitude</span>, <span class="arg">gravity</span>, <span class="arg">x_offset</span>=0, <span class="arg">y_offset</span>=0) -&gt;
        <em>image</em>
      </p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>Uses <span class="arg">displacement_map</span> to move color from <span class="arg">img</span> to the output image.</p>

      <p>
        This method corresponds to the -displace option of ImageMagick's
        <code>composite</code> command.
      </p>

      <h4>Arguments</h4>

      <dl>
        <dt>displacement_map</dt>

        <dd>The source image for the composite operation. Either an imagelist or an image. If an imagelist, uses the current image.</dd>

        <dt>x_amplitude</dt>

        <dd>The maximum displacement on the x-axis.</dd>

        <dt>y_amplitude</dt>

        <dd>
          The maximum displacement on the y-axis. This argument may omitted if no other arguments follow it. In this case the default is the value of
          <span class="arg">x_amplitude</span>.
        </dd>
      </dl>

      <p>
        The <code>displace</code> method can be called with or without a <span class="arg">gravity</span> argument. The <span class="arg">gravity</span>,
        <span class="arg">x_offset</span>, and <span class="arg">y_offset</span> arguments are described in the documentation for
        <a href="image3.html#watermark">watermark</a>.
      </p>

      <h4>Example</h4>

      <p>
        See
        <a href="https://www.imagemagick.org/Usage/compose/#displace"> "Composite Displacement Maps"</a>
        in Anthony Thyssen's
        <cite><a href="https://www.imagemagick.org/Usage/">Examples of ImageMagick Usage</a></cite
        >.
      </p>

      <h4>Returns</h4>

      <p>A new image</p>

      <h4>See also</h4>

      <p><a href="#composite">composite</a></p>
    </div>

    <div class="sig">
      <h3 id="display">display</h3>

      <p><span class="arg">img</span>.display [ <span class="arg">{ optional arguments }</span> ] -&gt; <em>self</em></p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>Display the image on an X Window screen. By default, the screen is the local monitor. Right-click the window to display a context menu.</p>

      <h4>Arguments</h4>

      <p>
        You can specify additional arguments by setting Info attributes in a block associated with the method call. Specifically, you can set the name of a
        non-default X Window screen with the
        <code><a href="info.html#Info.server_name_eq">server_name</a></code>
        attribute.
      </p>

      <h4>Returns</h4>

      <p>self</p>

      <h4>Note</h4>

      <p>The display method is not supported on native MS Windows.</p>

      <h4>Magick API</h4>

      <p>DisplayImages</p>
    </div>

    <div class="sig">
      <h3 id="dissolve">dissolve</h3>

      <p>
        <span class="arg">img</span>.dissolve(<span class="arg">overlay</span>, <span class="arg">src_percentage</span>,
        <span class="arg">dst_percentage</span>, <span class="arg">x_offset</span>=0, <span class="arg">y_offset</span>=0) -&gt; <em>image</em><br />
        <span class="arg">img</span>.dissolve(<span class="arg">overlay</span>, <span class="arg">src_percentage</span>,
        <span class="arg">dst_percentage</span>, <span class="arg">gravity</span>, <span class="arg">x_offset</span>=0, <span class="arg">y_offset</span>=0)
        -&gt; <em>image</em>
      </p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>
        Composites the <span class="arg">overlay</span> image into the target image. The opacity of <span class="arg">img</span> is multiplied by
        <span class="arg">dst_percentage</span> and opacity of <span class="arg">overlay</span> is multiplied by <span class="arg">src_percentage</span>.
      </p>

      <p>
        This method corresponds to the -dissolve option of ImageMagick's
        <code>composite</code> command.
      </p>

      <h4>Arguments</h4>

      <dl>
        <dt>overlay</dt>

        <dd>The source image for the composite operation. Either an imagelist or an image. If an imagelist, uses the current image.</dd>

        <dt>src_percentage</dt>

        <dd>
          Either a non-negative number a string in the form "NN%". If
          <span class="arg">src_percentage</span> is a number it is interpreted as a percentage. Both 0.25 and "25%" mean 25%. This argument is required.
        </dd>

        <dt>dst_percentage</dt>

        <dd>
          Either a non-negative number a string in the form "NN%". If
          <span class="arg">src_percentage</span> is a number it is interpreted as a percentage. Both 0.25 and "25%" mean 25%. This argument may omitted if no
          other arguments follow it. In this case <span class="arg">img</span>'s opacity is unchanged.
        </dd>
      </dl>

      <p>
        The <code>dissolve</code> method can be called with or without a <span class="arg">gravity</span> argument. The <span class="arg">gravity</span>,
        <span class="arg">x_offset</span>, and <span class="arg">y_offset</span> arguments are described in the documentation for
        <a href="image3.html#watermark">watermark</a>.
      </p>

      <h4>Example</h4>

      <p>
        See "
        <a href="https://www.imagemagick.org/Usage/compose/#dissolve"> Dissolve One Image Over Another</a>" in Anthony Thyssen's
        <cite><a href="https://www.imagemagick.org/Usage/">Examples of ImageMagick Usage</a></cite
        >.
      </p>

      <p><code>bgnd.dissolve(overlay, 0.50, 1.0)</code></p>

      <p class="rollover">
        <a href="javascript:popup('dissolve.rb.html')"
          ><img
            onmouseover="this.src='ex/images/Flower_Hat.jpg'"
            onmouseout="this.src='ex/dissolve.jpg'"
            src="ex/dissolve.jpg"
            alt="dissolve example"
            title="Click to see the example script"
        /></a>
        <img src="ex/images/spin.gif" alt="" class="spin" title="Mouse over the example to see the original image" />
      </p>

      <h4>Returns</h4>

      <p>A new image</p>

      <h4>See also</h4>

      <p><a href="#blend">blend</a>, <a href="#composite">composite</a></p>
    </div>

    <div class="sig">
      <h3 id="distort">distort</h3>

      <p>
        <span class="arg">img</span>.distort(<span class="arg">type</span>, <span class="arg">points</span>,
        <span class="arg">bestfit</span>=<code>false</code>) [ <span class="arg">{&nbsp;optional arguments&nbsp;}</span> ] -&gt;
        <em>image</em>
      </p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>Distort an image using the specified distortion type and its required arguments. This method is equivalent to ImageMagick's -distort option.</p>

      <h4>Arguments</h4>

      <dl>
        <dt>type</dt>

        <dd>
          One of the following values:

          <ul>
            <li>AffineDistortion</li>

            <li>AffineProjectionDistortion</li>

            <li>ArcDistortion</li>

            <li>BarrelDistortion</li>

            <li>BarrelInverseDistortion</li>

            <li>BilinearDistortion</li>

            <li>PerspectiveDistortion</li>

            <li>PerspectiveProjectionDistortion</li>

            <li>PolynomialDistortion</li>

            <li>ScaleRotateTranslateDistortion</li>

            <li>ShepardsDistortion</li>
          </ul>
        </dd>

        <dt>points</dt>

        <dd>An array of numbers. The size of the array depends on the distortion type.</dd>

        <dt>bestfit</dt>

        <dd class="imquote">
          If <span class="arg">bestfit</span> is enabled, and the distortion allows it, the destination image is adjusted to ensure the whole source image will
          just fit within the final destination image, which will be sized and offset accordingly. Also in many cases the virtual offset of the source image
          will be taken into account in the mapping.
        </dd>

        <dt>optional arguments</dt>

        <dd>
          If present, <code>distort</code> yields to a block in which you can set optional arguments by calling methods on <em>self</em>.

          <dl>
            <dt>options.define("distort:viewport", "WxH+X+Y")</dt>

            <dd>
              Specify the size and offset of the generated viewport image of the distorted image space. W and H are the width and height, and X and Y are the
              offset.
            </dd>

            <dt>options.define("distort:scale", N)</dt>

            <dd>
              N is an integer factor.
              <span class="imquote"
                >Scale the output image (viewport or otherwise) by that factor without changing the viewed contents of the distorted image. This can be used
                either for 'super-sampling' the image for a higher quality result, or for panning and zooming around the image (with appropriate viewport
                changes, or post-distort cropping and resizing).</span
              >
            </dd>

            <dt>options.verbose(true)</dt>

            <dd class="imquote">
              Attempt to output the internal coefficients, and the -fx equivalent to the distortion, for expert study, and debugging purposes. This many not be
              available for all distorts.
            </dd>
          </dl>
        </dd>
      </dl>

      <h4>Returns</h4>

      <p>A new image</p>

      <h4>Example</h4>
      <pre>
result = img.distort(Magick::ScaleRotateTranslateDistortion, [0]) do |options|
  options.define "distort:viewport", "44x44+15+0"
  options.define "distort:scale", 2
end
</pre
      >

      <h4>Note</h4>

      <p>
        See
        <a href="https://www.imagemagick.org/Usage/distorts/#distort">Distortion Operator</a>
        in Anthony Thyssen's excellent
        <a href="https://www.imagemagick.org/Usage/">Examples of ImageMagick Usage</a>
        for more information about distortion operations.
      </p>
    </div>

    <div class="sig">
      <h3 id="distortion_channel">distortion_channel</h3>

      <p>
        <span class="arg">img</span>.distortion_channel(<span class="arg">reconstructed_image</span>, <span class="arg">metric</span>[,
        <span class="arg">channel</span>...]) -&gt; <em>float</em>
      </p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p class="imquote">(C)ompares one or more image channels of an image to a reconstructed image and returns the specified distortion metric.</p>

      <h4>Arguments</h4>

      <dl>
        <dt>reconstructed_image</dt>

        <dd>Either an imagelist or an image. If an imagelist, uses the current image.</dd>

        <dt>metric</dt>

        <dd>
          The desired distortion metric. A
          <a href="constants.html#MetricType">MetricType</a> value.
        </dd>

        <dt>channel...</dt>

        <dd>
          Zero or more
          <a href="constants.html#ChannelType">ChannelType</a> values. All the specified channels contribute to the comparison and the distortion value. If no
          channels are specified, compares all channels.
        </dd>
      </dl>

      <h4>Returns</h4>

      <p>The distortion metric, represented as a floating-point number.</p>

      <h4>Magick API</h4>

      <p>GetImageChannelDistortion</p>

      <h4>See also</h4>

      <p>
        <a href="#compare_channel">compare_channel</a>,
        <a href="#difference">difference</a>
      </p>
    </div>

    <div class="sig">
      <h3 id="dup">dup</h3>

      <p><span class="arg">img</span>.dup -&gt; <em>other_image</em></p>
    </div>

    <div class="desc">
      <h4>Description</h4>

      <p>Same as <a href="#copy">copy</a>.</p>

      <h4>Returns</h4>

      <p>A new image</p>

      <h4>See also</h4>

      <p><a href="#clone">clone</a></p>
    </div>

    <p class="spacer">&nbsp;</p>

    <div class="nav">&laquo;&nbsp;<a href="imageattrs.html">Prev</a> | <a href="index.html">Contents</a> | <a href="image2.html">Next</a>&nbsp;&raquo;</div>
  </body>
</html>
